@verdacert/ai-sdk-tools

Verdacert — USCIS-certified translation as an API for AI agents — wrapped as a typed Vercel AI SDK tool catalog.

Drop one import into your generateText, streamText, or agent loop and your model can quote, submit, poll, and verify certified translations end-to-end.

import { generateText } from "ai";
import { createVerdacertTools } from "@verdacert/ai-sdk-tools";

const tools = createVerdacertTools({
  apiKey: process.env.VERDACERT_API_KEY!,
});

const { text } = await generateText({
  model: "anthropic/claude-sonnet-4",
  tools,
  prompt:
    "Quote a 3-page Farsi birth certificate for USCIS. Show me the price.",
});

Install

pnpm add @verdacert/ai-sdk-tools ai zod
# or
npm i @verdacert/ai-sdk-tools ai zod

ai (v5 or v6) and zod (v3 or v4) are peer dependencies — bring your own version.

Get an API key

Self-serve at verdacert.com/onboarding. You'll get a sandbox key (vc_sandbox_…) immediately and can mint a live key (vc_live_…) once you've added a payment method.

Sandbox keys run a deterministic state machine — no real translation, no charge — and are perfect for development.

Tools

createVerdacertTools() returns an object with seven tools. All of them mirror the REST + MCP surface; there is one source of truth on the server.

| Tool | What it does | | ------------------- | -------------------------------------------------------------------- | | getCapabilities | List supported languages, document types, tiers, add-ons. | | quote | Binding price + ETA. Free, cacheable. Returns a 24h-valid quoteId. | | submit | Place the order. Idempotent on (apiKey, idempotencyKey). | | getStatus | Poll progress. Safe to back off — recommended start at 30s. | | getResult | Fetch the certified PDF + JWS receipt for a ready job. | | refund | Full or partial refund within the 30-day window. | | verifyCertificate | Independently verify a Verdacert certificate id. |

Options

createVerdacertTools({
  apiKey: process.env.VERDACERT_API_KEY!,

  // Optional overrides:
  baseUrl: "https://verdacert.com",      // change for staging or self-host
  fetch: globalThis.fetch,               // inject for tracing or retries
  defaultHeaders: { "x-trace-id": "…" }, // forwarded on every call
});

Errors

Non-2xx responses throw VerdacertHttpError:

import { VerdacertHttpError } from "@verdacert/ai-sdk-tools";

try {
  await tools.submit.execute(input, /* ai sdk passes a 2nd arg */);
} catch (err) {
  if (err instanceof VerdacertHttpError) {
    console.error(err.body.code);        // e.g. "QUOTE_EXPIRED"
    console.error(err.body.recoveryHint);// e.g. "Call quote() again."
    console.error(err.requestId);        // hand this to Verdacert support
  }
}

When tools are invoked by the AI SDK, errors are surfaced through the SDK's tool-result channel and the model can react to them in the next turn. The recovery hints on each error are tuned for that path.

Subset / extend

Need only some tools? Destructure:

const { quote, submit, getStatus, getResult } = createVerdacertTools({
  apiKey: process.env.VERDACERT_API_KEY!,
});

const { text } = await generateText({
  model: "anthropic/claude-sonnet-4",
  tools: { quote, submit, getStatus, getResult },
  prompt: "…",
});

Want to wrap or instrument a tool? Each entry is a plain AI SDK Tool — compose freely.

Verifying certificates client-side

Verdacert signs every certificate with Ed25519 over a deterministic JSON payload and publishes the JWKS at /.well-known/jwks.json.

verifyCertificate round-trips through the API and returns the parsed envelope plus a compact JWS. If you want to verify entirely offline:

import { jwtVerify, createRemoteJWKSet } from "jose";

const jwks = createRemoteJWKSet(
  new URL("https://verdacert.com/.well-known/jwks.json"),
);

const result = await tools.verifyCertificate.execute(
  { certificateId: "vcrt_…" },
  /* ai sdk passes a 2nd arg */,
);

const { payload, protectedHeader } = await jwtVerify(result.jws, jwks);

Reference agent

A full working example — Claude using these tools to walk a paralegal through certifying an immigration case file — lives in examples/immigration-paralegal.

Pricing & rev-share

• Per-order pricing is returned by quote and matches the public rate card.
• Platforms that route paid orders through their own API key earn a revenue share. The exact bps is set on your account; the per-order payout is surfaced on getResult responses under .referral.
• Payouts are batched monthly via Stripe Connect.

Reach out at [email protected] for custom terms.

License

MIT — see LICENSE.