Verafirma logo Verafirma
View as Markdown ↓

The lodestone path

An AI agent makes ONE HTTPS call to POST /v1/envelopes with a PDF, a recipient email, and an x402 payment authorization, gets back a signing URL, and never created an account.

This is the canonical use case the API is designed around. Every architectural decision is judged against it: does this make the lodestone harder? If yes, it doesn’t ship.

Why this matters

Most APIs assume a customer relationship: account, dashboard, billing portal, monthly invoice. That assumption breaks for two cases:

  1. AI agents running on someone else’s machine, with a process and a config and possibly a private key — but no email, no password, no phone number, no ability to click confirmation links or fill captchas.
  2. One-shot integrations where the developer wants to use the API once, never again, and never get billed for nothing in between.

The lodestone path serves both. There is no account-creation flow. There is no JWT mint. There is no “wallet auth challenge.” The agent constructs one HTTPS request that carries everything, and the request is the entire interaction.

What “one call” actually means

Three pieces are bundled into the request:

  1. The payload — a multipart upload with a PDF and a JSON object describing the recipient(s), title, optional fields, optional storage expiry.
  2. The payment authorization — a PAYMENT-SIGNATURE header carrying a base64-encoded EIP-3009 transferWithAuthorization signed off-chain by the wallet that’s paying. Off-chain means no gas; settlement happens server-side via Relaystation’s facilitator.
  3. An idempotency key — Idempotency-Key header. Mandatory on billable operations. Re-submissions with the same key return the original response without double-billing.

The response is a 201 Created with the envelope id, its current Documenso state, and per-recipient signing URLs. Settlement is synchronous: by the time the response returns, the wallet has been debited.

Wallet IS the identity

The lodestone has no signin step. So how does the wallet customer ever see their own history later?

The wallet address that signed the EIP-3009 authorization IS the identity. Relaystation upserts a wallet-kind customer record on the first x402 admit and reuses it on subsequent calls. If the same wallet wants to read its envelope history later, it goes through the wallet JWT path: exchange an EIP-191 signature for a JWT, then use the JWT against /v1/account/* reads.

The two flows use different cryptographic primitives — EIP-3009 for the payment authorization (per-call), EIP-191 for the wallet-as-identity signin (returning visits) — but they bind to the same wallet address, and the customer record persists across both. (See the drift hazards section below for why this distinction matters.)

What’s wrapped, what’s not

The lodestone is a thin wrapper:

  • Documenso owns the signing engine: PDFs, recipients, fields, signing UI, audit log, completed-PDF generation. The wrapper translates payload shape, calls Documenso, returns the result.
  • Relaystation owns billing: x402 settlement, wallet customer records, balance tracking, refund primitives. The wrapper hands the payment header to the Relaystation SDK and gets back a charged context.

The wrapper itself does input validation, idempotency, terminal-event refund coordination, and outbound webhook fan-out. Nothing in the lodestone path requires any persistent verafirma-side state for the caller — wallet customers don’t get a row in the verafirma database.

When NOT to use the lodestone

  • You want a single key for many calls. Mint a vf_live_* API key after OAuth signup. Same envelope creation; bearer auth instead of x402.
  • You want pre-funded calls without per-call gas. Top up via Stripe. Same key, debits from balance.
  • You want a dashboard. OAuth signup at app.verafirma.com gives you the key plus the customer surface.

These three modes share one identity (Relaystation’s customer record) and one billing model (Relaystation’s wallet). The lodestone is one call shape; the others are key-based variants of the same underlying flow.

Drift hazards

A few substitutions look reasonable but are wrong on the per-call path. Don’t make them.

  • Not EIP-191 / SIWE / personal_sign on the per-call path. Those are wallet-as-identity primitives, used for the wallet JWT signin (returning visits). The per-call payment authorization is EIP-3009, not EIP-191. Different signing scheme, different domain separator, different recovered address.
  • Not a separate signin step before the call. That’s the API-key-with-Stripe-wallet mode (mode 2/3). The lodestone is one call, period.
  • Not a deposit-then-withdraw exchange model. That’s a deferred Relaystation V2 deliverable. Today the lodestone settles per-call; deposits onto a wallet are not a V1 surface.
  • Not a custom x402 variant. x402 is a real spec; standard client libraries work against the endpoint. Don’t invent a header shape that locks customers in.

Reference reading

  • The wire format is at /concepts/x402; Relaystation’s docs/protocols/x402.md is the authoritative source for the protocol.
  • The pricing surface is at /pricing.
  • The authentication modes (lodestone vs API key vs wallet JWT vs same-origin cookie) are summarized at /concepts/authentication.
  • The full machine-readable surface is at /openapi.json.