# Verafirma

> Pay-per-call eSignature for developers + AI agents.

## Instructions

This API is built for AI agents. The fastest path is one HTTPS request:

`POST /v1/envelopes` carries a 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. No signup is required for the per-call path; the wallet that signs the payment is the identity for any later history reads.

**Pricing:** $0.10 per envelope. Pay per call — no minimum. Refunded automatically on terminal failure (REJECTED / EXPIRED / CANCELLED) up to a per-envelope cap.

**Wire format authority:** the x402 payment shape is defined by the protocol document at `relaystation/docs/protocols/x402.md`. The envelope creation surface is 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 four V1 tools (`verafirma.create_signing_request`, `verafirma.get_envelope_status`, `verafirma.list_envelopes`, `verafirma.register_webhook`) wrap the REST handlers.

**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.
- `/health` is for ops, not customers. The OpenAPI surface intentionally hides it from customer-facing renders.

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.
- [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)