Skip to main content
Every other payment path on paperplane ends at a Stripe-hosted payment_url a human has to open. That’s correct for a human-approved send and a dead end for a funded autonomous agent — an AWS Bedrock AgentCore payment, an x402-wallet bot, or an agent marketplace buyer — that transacts machine-to-machine with no person in the loop. POST /v1/x402/credits (and the buy_credits MCP tool) is that path: an agent pays USDC on Base directly from its own wallet, using the x402 protocol’s plain HTTP-402 challenge/response handshake, and receives a prepaid paperplane credit code it then spends with send_letter or POST /v1/orders.
Status: staged, not live. The full x402 v2 handshake — challenge, verify, settle, mint — is real, tested code. It reports x402_not_configured (HTTP 501) on every deployment today because going live needs two provisioning steps that are deliberately out of scope for this build: a Coinbase Developer Platform (CDP) facilitator account, and enabling “Stablecoins and Crypto” as a payment method on paperplane’s Stripe account. sandbox: true works today regardless — see below.

​
Why credits, not a direct paid send

x402 sells credits, not a one-shot paid letter. A credit is refundable by policy even though on-chain settlement itself is final — see Refunds below — and reuses the exact redemption, expiry, and ledger logic every other credit purchase already goes through (see Credits). Buying credits over x402 and then spending them with send_letter’s credit_code is two well-tested capabilities composed, not a new one.

​
The flow

1

1. Ask for a price

Call POST /v1/x402/credits (or buy_credits) with { pack, email } and no payment. The response is HTTP 402 with a payment_required code and a full x402 payment-requirements challenge: network, amount, the payTo address, asset.
2

2. Sign and pay

Your wallet signs the challenge (x402 v2 “exact” scheme — typically a gasless EIP-3009 transferWithAuthorization on Base USDC) and produces a payment payload.
3

3. Settle

Call the same endpoint again with the signed payload in the X-PAYMENT header (REST) or payment_header (MCP). The server verifies and settles against the configured CDP facilitator, then mints a credit code.
4

4. Spend it

Pass the returned credit_code to send_letter or POST /v1/orders. The letter moves immediately — no further payment step, human or agent.
402 Payment Required
201 Created — settled
A repeated call with the same signed payload (a client retry after a dropped response) replays the original credit_code with replayed: true rather than minting a second one — the settlement’s transaction hash is the idempotency key.

​
Sandbox: works today, no provisioning needed

Pass sandbox: true and the endpoint mints a real, spendable credit code immediately — no wallet, no facilitator call, no charge — even while x402 itself is disabled on the deployment. That is deliberate: the whole agent-payments lane has to be integration-testable for free before any CDP account or Stripe toggle exists, the same promise sandbox: true already makes on POST /v1/orders.

​
Refunds

x402 settlement is final on-chain — there is no chargeback and no native refund mechanism, unlike a card payment. That does not make the purchase unrefundable:
  • An unredeemed credit is refundable by policy, same as any other credit pack — issued back as paperplane credit, or on request as a voluntary USDC return.
  • Undeliverable-mail guarantees still pay out, always in credit (never a reversed on-chain transfer, which is not possible).
Publishing this plainly, here, before any real settlement happens is itself a requirement of the design — see docs/PRD-agentic-payments.md.

​
Geography

Stripe does not offer the “Stablecoins and Crypto” payment method in every region — New York is excluded today. The endpoint hides the lane there: a request from an unsupported region gets region_unsupported (HTTP 403) instead of a payment challenge, pointing back at POST /v1/credits/checkout or a prepaid credit_code. This is Stripe’s exclusion, not a paperplane policy choice.

​
buy_credits (MCP)

Same handshake, over MCP, for an agent that holds a wallet directly:
See the MCP guide for the other three tools and the quote → confirm → send discipline buy_credits sits alongside.

​
Errors

x402_not_configured, payment_required, x402_payment_invalid, x402_verify_failed, x402_settle_failed, and region_unsupported are all in the error contract with the same { status, code, reason, next } shape every other paperplane failure uses.
Last modified on September 17, 2026