Aly Sawft · Founder & Engineer, Sawftware LLC · · 9 min read
DocImprint supports two authentication models on every paid endpoint. The API surface is identical — the same POST /v1/extract request works with either. x402 follows the HTTP 402 micropayment protocol at x402.org. Only the Authorization mechanism differs.
x402: send no auth header. The server responds with 402 and payment requirements. Sign a USDC transfer on Base and retry. The agent's wallet identity becomes the bundle owner.
API keys: send Authorization: Bearer dr_live_.... The API key is tied to a Stripe subscription plan with monthly credits. Usage is deducted from your credit balance.
Both are production-ready. Neither is a "beta" feature. The choice between them is a product and operations decision, not a technical one.
x402 is designed for autonomous agents that cannot hold credentials. Choose x402 when:
The caller is a long-running autonomous agent. An agent running inside a LLM framework cannot store API keys securely (they would be visible in the prompt or the agent's memory). A wallet private key can be held in a secure enclave or injected at runtime without appearing in the agent's context.
You want true pay-as-you-go. With API keys, you buy a plan and get credits. Credits expire. With x402, you pay exactly for what you use, at the moment you use it — no minimum commitment, no monthly charge, no expired credits.
Wallet identity matters. When an agent pays with x402, its wallet address is recorded as the bundle owner. Owner-scoped routes (GET bundle, manage collections, set legal hold) require the same wallet identity. This creates a cryptographic chain of ownership: the agent that paid for the extraction is the provable owner of the resulting evidence bundle.
You are building a multi-tenant system where each user funds their own API usage. Each user wallet pays for its own calls. No central API key management, no per-user key provisioning, no secret rotation.
You are already in the Base/USDC ecosystem. If your product already handles on-chain transactions, adding x402 is additive. If it does not, there is an onboarding cost.
API keys work better in several common scenarios:
You are a developer building and testing. API keys are simpler to set up — get a key from the dashboard, add an Authorization header, done. No wallet setup, no USDC balance to maintain, no gas fee concerns during development.
You want predictable monthly billing. x402 costs vary with usage. API key plans give you a fixed monthly credit budget. For enterprise teams with finance approval processes, a monthly invoice is operationally simpler than a stream of USDC transfers.
You are running batch jobs. Processing thousands of documents in a batch job is straightforward with API keys: provision one key, run the job, check the bill. x402 for batch processing requires pre-funding a wallet, batching transactions, and handling per-call signature overhead.
Your organization has a no-crypto policy. Some organizations prohibit on-chain transactions for compliance, regulatory, or policy reasons. API keys work within standard payment infrastructure.
You need team access control. API keys can be scoped and rotated. Multiple team members can each have their own key. x402 wallet management across a team is more complex.
The per-call pricing is identical regardless of auth method. A full extract bundle costs $0.075 whether you pay with USDC or with API key credits.
The difference is in the pricing model:
x402: pure pay-as-you-go. $0.075 per extract call, charged at call time in USDC. No monthly fee, no minimum. Ideal if your usage is bursty or unpredictable.
API key plans: monthly subscription with credits. The Starter plan includes 1,000 credits/month. Credits are 1:1 with dollars — 1,000 credits = $1.00 of API calls. Plan pricing is typically 15–20% cheaper per call than pay-as-you-go, in exchange for the monthly commitment.
For consistent moderate usage (100+ extract calls/month), an API key plan is more economical. For occasional or unpredictable usage, x402 avoids paying for credits you do not use.
There are no additional charges for verification (GET .../verify) or download (GET .../download) with either auth method — those endpoints are always free.
Latency: x402 adds one round trip. The probe returns 402, the client signs and retries. A typical extract call adds ~100–300ms for the probe-retry cycle. API key calls are single-round-trip. For latency-sensitive applications, API keys are faster.
Rate limits: both auth methods have per-second rate limits. API key rate limits are tied to your plan tier. x402 rate limits are per wallet address, based on on-chain payment verification speed.
Bundle ownership: with x402, the bundle owner is the payment wallet address. With API keys, the bundle owner is the API key identity (key ID). Both support owner-scoped routes — the syntax differs slightly. x402 owner routes require X-Wallet-Address header; API key owner routes use the key's identity automatically.
Error handling: x402 payment failures (insufficient USDC, invalid signature, nonce reuse) return specific error codes in the 402 response body. API key failures (expired key, insufficient credits, invalid key format) return 401 or 402 with different error codes. Handle both if you support both auth methods in the same codebase.
# x402 — no credential, USDC payment on retry
curl -X POST https://api.docimprint.com/v1/extract \
-H "Content-Type: application/json" \
-H "X-Payment: <signed-usdc-transfer>" \
-d '{"source":"https://example.com/doc.pdf"}'
# API key — credential in Authorization header
curl -X POST https://api.docimprint.com/v1/extract \
-H "Content-Type: application/json" \
-H "Authorization: Bearer dr_live_abc123..." \
-d '{"source":"https://example.com/doc.pdf"}'
# Response is identical for both — same JSON envelope, same bundle structureBoth auth models are secure when implemented correctly, but they fail in different ways.
API keys are bearer tokens. Anyone who possesses the key can make calls until the key is revoked. Keys leak through environment variables in CI logs, committed .env files, shared Slack messages, and agent prompts that accidentally include credentials. Rotation is the mitigation: issue per-environment keys, rotate on schedule, and revoke immediately on suspected leak.
x402 has no long-lived secret in the request path. The wallet private key signs each payment individually. A leaked signature is useless after the nonce is consumed — DocImprint deduplicates payment nonces in KV with TTL, so replay attacks fail. The remaining risk is wallet key compromise, which is equivalent to API key compromise but scoped to on-chain funds rather than unlimited API access.
For agent deployments, x402 reduces the blast radius: a compromised agent wallet loses its USDC balance, not your entire production API key with unlimited monthly credits. You can fund agent wallets with small amounts and monitor on-chain debits. API key compromise can exhaust an entire credit pool before you notice.
Neither model replaces authorization on owner-scoped routes. x402 bundles require X-Wallet-Address matching the payment wallet. API key bundles require the same key that created them. Cross-tenant access is blocked in both cases — the auth model determines identity, not access control granularity.
Most production systems that serve both human developers and autonomous agents use both auth methods simultaneously.
A common pattern: API keys for your backend services, CI pipelines, and internal dashboards; x402 for user-facing agent integrations where each end user funds their own wallet. Your platform code branches on auth type at the HTTP layer but shares the same downstream processing.
Another pattern: API keys during development and staging (fast iteration, predictable billing), x402 in production agent flows (wallet identity, pay-as-you-go). DocImprint staging on Base Sepolia accepts mock x402 signatures — you can test the full probe-retry flow without real USDC while using API keys for integration tests.
Marketplace integrations (Claude, GPT store, A2A orchestrators) typically require x402 because operators cannot provision API keys per end user at scale. Your own admin tools use API keys because operators already have dashboard access.
The SDK and curl examples in the docs show both patterns side by side. Switching auth requires changing headers only — request bodies, response parsing, bundle management, and collection workflows are identical.
# API key — check remaining credits
curl https://api.docimprint.com/v1/billing/usage \
-H "Authorization: Bearer dr_live_..."
# x402 — check wallet USDC balance on Base (outside DocImprint)
# Use any Base RPC or block explorer for address 0xYourAgentWallet...
# DocImprint returns 402 with maxAmountRequired before each call — no pre-check endpoint neededSwitching auth models does not require re-architecting your integration. The API surface, bundle structure, and collection semantics are auth-agnostic.
Migrating from API keys to x402:
Migrating from x402 to API keys:
There is no bulk ownership transfer endpoint — bundles are permanently bound to the identity that paid for or created them. Plan identity mapping before production if you expect to switch auth models mid-lifecycle.
For agents that start with API keys and later move to x402, the cleanest path is to treat it as a new deployment: new wallet, new bundles, new collections. Re-extract critical documents under the new identity if ownership continuity matters.
Use x402 if:
Use API keys if:
Use both if:
There is no wrong answer. Both methods are stable, documented, and supported by DocImprint. Start with whichever fits your current context; migrating later requires only changing the auth mechanism, not the API calls themselves.