# Verafirma

> Pay-per-call eSignature + ID verification. $0.10 per call.

## Instructions

This API is built for AI agents. Two products, same shape — each is one HTTPS request.

**Send a contract for signature: `POST /v1/envelopes`.** Multipart upload (PDF + JSON payload describing recipients) plus a `PAYMENT-SIGNATURE` header (base64-encoded EIP-3009 `transferWithAuthorization` over USDC v2 on Base). The response is a signing URL the recipient can use immediately. **$0.10 per envelope.**

**Verify an ID: `POST /v1/verifications`.** JSON body with `[component]`; same `PAYMENT-SIGNATURE` header shape. The response is a hosted URL the end-user opens to upload their ID and selfie. We webhook you the result. **$0.10 per verification.**

No signup is required for the per-call path on either product; the wallet that signs the payment is the identity for any later history reads. Same wallet → same balance → same history across both products.

**Pricing:** $0.10 per call, both products. Pay per call — no minimum, no subscription. Envelopes refund automatically on terminal failure (`REJECTED` / `EXPIRED` / `CANCELLED`) up to a per-envelope cap; verifications refund on `verification.failed` up to `verafirma.verification.refund_cap_per_call` (default 1).

**Wire format authority:** the x402 payment shape is defined by the protocol document at `relaystation/docs/protocols/x402.md`. The two creation surfaces are documented in the OpenAPI spec at `/openapi.json`. Use a standard x402 client library to construct the payment payload — don't construct the JSON by hand.

**Discovery surfaces (use these to navigate, not just to find this page):**

- `/openapi.json` — full machine-readable API surface.
- `/llms-full.txt` — concatenated raw markdown of every page below, no token cap.
- `/.well-known/mcp` — MCP endpoint advertisement (SEP-1960 shape).
- `/.well-known/mcp/server-card.json` — MCP rich card with tool summaries (SEP-1649 shape).
- `https://api.verafirma.com/mcp` — streamable-HTTP MCP server. The V1 tools wrap the REST handlers for both products: `verafirma.create_signing_request`, `verafirma.get_envelope_status`, `verafirma.list_envelopes`, `verafirma.register_webhook` (envelope surface), plus the verification handlers as they roll into MCP. The authoritative list is the `tools/list` response.

**Drift hazards to know:**

- The per-call payment uses **EIP-3009**, NOT EIP-191 or SIWE or `personal_sign`. EIP-191 IS used elsewhere — for the wallet-JWT signin on the dashboard-read path — but that's a different flow.
- Three documented payment modes exist (x402 per-call, API-key Stripe-funded wallet, wallet-JWT for reads). Don't substitute one for another based on apparent similarity; the auth header shape and billing primitive differ.
- The two products share the SAME billing rails. There is no per-product entitlement gate; every authed customer can call both `/v1/envelopes` and `/v1/verifications`. x402 callers were never gated.
- `/health` is for ops, not customers. The OpenAPI surface intentionally hides it from customer-facing renders.

**Anti-lock-in posture:** Verafirma hosts open-source software ourselves and charges what it costs to run plus a markup. When your volume grows past the point where running it yourself makes sense, ask us — we'll point you at the upstream we use so you can replace us cleanly. No proprietary SDK to throw away; the on-the-wire contract is standard HTTPS + x402.

If something doesn't work, the error response carries a `code` field. The full code catalog is at `/docs/errors`. For 5xx upstream errors, retry with the same `Idempotency-Key` header — duplicates collapse to the original response.

## Concepts

- [Authentication modes](https://verafirma.com/docs/authentication): Three modes: API key (Stripe-funded wallet), x402 wallet (per-call), wallet JWT (dashboard reads). Plus same-origin cookie for browser sessions.
- [Envelopes](https://verafirma.com/docs/envelopes): An envelope is a PDF + recipients + fields. Status flow: DRAFT → SENT → PARTIALLY_SIGNED → COMPLETED.
- [Lodestone](https://verafirma.com/docs/lodestone): One HTTPS call carries payload + payment; the agent gets a signing URL and never created an account.
- [MCP discovery](https://verafirma.com/docs/mcp): Point an MCP client at /mcp; tools wrap the same handlers as REST; auth flows through the same modes.
- [Verification](https://verafirma.com/docs/verification): Verify identity in one HTTPS call. $0.10 per check. Pay per use; no subscriptions.
- [Outbound webhooks](https://verafirma.com/docs/webhooks): Register a URL, verify HMAC signatures on inbound deliveries, react to seven V1 events.
- [x402 wire format](https://verafirma.com/docs/x402): EIP-3009 transferWithAuthorization signed off-chain on the per-call path. Not EIP-191 / SIWE / personal_sign — those belong to the wallet-JWT path.

## Guides

- [Errors](https://verafirma.com/docs/errors): Error response shape, common error codes, where to read the audit log.
- [Quickstart](https://verafirma.com/docs/quickstart): First curl in five lines: POST /v1/envelopes with PDF + recipient + payment auth → signing URL.

## API Reference

- [OpenAPI 3.1 spec](https://verafirma.com/api-reference): Full machine-readable surface. Audience-filtered + augmented with x-verafirma-audience extensions.

## Pricing

- [Pricing](https://verafirma.com/pricing): Pay per call. No subscription, no minimum, no commitment. Refunded automatically on terminal failure within cap.

## Discovery

- [OpenAPI 3.1 spec](https://api.verafirma.com/openapi.json)
- [Web-rendered API reference](https://verafirma.com/api-reference)
- [MCP endpoint](https://api.verafirma.com/mcp)
- [llms-full.txt](https://verafirma.com/llms-full.txt)