# The lodestone path _One HTTPS call carries payload + payment. The agent gets a signing URL and never created an account._ _Last updated: 2026-05-07_ --- # 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](/concepts/authentication): 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](#drift-hazards) 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`](/concepts/x402); Relaystation's `docs/protocols/x402.md` is the authoritative source for the protocol. - The pricing surface is at [`/pricing`](/pricing). - The authentication modes (lodestone vs API key vs wallet JWT vs same-origin cookie) are summarized at [`/concepts/authentication`](/concepts/authentication). - The full machine-readable surface is at [`/openapi.json`](/api-reference).