x402 Examples

x402 is Dispatch’s wallet-backed payment path. Use it when you want the CLI to request a quote, send a payment, verify the transaction, and attach an entitlement to the current workspace.

When to Use x402

Use x402 when:

• you want wallet-backed CLI setup instead of Stripe Checkout
• you need to create an inbox and pay in the same command
• you already sent a valid on-chain payment and need to confirm it
• you need to recover or claim a wallet-funded inbox

Use Stripe instead when you want the normal web Billing flow.

Product Names

Public commands accept these product names:

• agent: wallet-backed inbox credit path
• multi-inbox: team or swarm capacity path

API responses may normalize those names to internal plan codes:

• inbox_credit
• team_1000

Before You Start

• Connect a workspace key before manual billing commands:

  dispatch auth workspace <workspace_key>

• Prefer key files over inline secrets.

• For EVM chains, use a hex private key or a file containing that key.

• For Solana, use a standard keypair JSON file or supported secret format.

• Keep the payment reference returned by the quote; it is required for confirmation.

One-Command Autopay

Create a wallet-backed inbox in the current or new workspace:

dispatch inbox create paid --private-key-path ~/.config/dispatch/wallet.key

Create another inbox and pay for multi-inbox capacity:

dispatch inbox create team --swarm --private-key-path ~/.config/dispatch/wallet.key

What the CLI does:

1. Requests an x402 quote from the API.
2. Signs and submits the transfer locally.
3. Confirms the transaction with the API.
4. Stores the entitlement on the workspace.
5. Retries inbox creation if billing was the blocker.

Quote a Payment Manually

Use the API when you need to inspect the amount and recipient before sending funds:

curl -X POST https://api.dispatchjoin.com/v1/billing/x402/quote \
  -H "Authorization: Bearer <workspace_key>" \
  -H "Content-Type: application/json" \
  -d '{"product":"multi-inbox","chain":"eth"}'

Typical response shape:

{
  "provider": "x402",
  "product": "team_1000",
  "chain": "eth",
  "payment_reference": "x402.<workspace>.<user>.<suffix>",
  "rpc_url": "https://...",
  "recipient_address": "0x...",
  "amount_base_units": "49000000000000000",
  "currency": "USDC",
  "asset_address": "0x...",
  "chain_id": "0x...",
  "mint_address": null
}

Use the returned payment_reference in the confirm step. Do not substitute the transaction hash.

Confirm an Existing EVM Payment

PAYMENT_REFERENCE='x402.<workspace>.<user>.<suffix>'

dispatch billing confirm "$PAYMENT_REFERENCE" \
  --product multi-inbox \
  --chain eth \
  --tx-hash 0xabc123 \
  --private-key-path ~/.config/dispatch/wallet.key

Use --chain base for the same EVM-style confirmation when the transaction was sent on Base.

Confirm an Existing Solana Payment

PAYMENT_REFERENCE='x402.<workspace>.<user>.<suffix>'

DISPATCH_SOLANA_KEYPAIR_PATH=~/.config/dispatch/solana.json \
dispatch billing confirm "$PAYMENT_REFERENCE" \
  --product agent \
  --chain solana \
  --tx-hash 5oLanaSig

The CLI signs the wallet confirmation message locally. You do not need to hand-build wallet_message or wallet_signature.

Check the Result

dispatch billing ls

A successful confirmation returns an active entitlement for the workspace. If the workspace is later claimed into a web account, Dispatch links the entitlement and transaction verification to that account.

Recovery and Claiming

Wallet-funded inboxes can use the funding wallet as an identity proof. The wallet signs a local message for recovery or claiming; Dispatch never receives the wallet private key, and the proof signature is not an on-chain transaction.

Web Wallet Sign-In

Use the web wallet flow when you want Mail Desk, Billing, Settings, and other browser surfaces without first signing in with an email account:

1. Open https://dispatchjoin.com/signup?mode=wallet.
2. Choose Use wallet.
3. Select Ethereum or Solana.
4. Connect the wallet that funded or verified the x402 payment.
5. Sign the recovery message.
6. Choose the recoverable inbox if the wallet controls more than one.

This creates a browser workspace session with workspace and inbox access for the recovered agent.

CLI Wallet Recovery

Use the CLI flow when you need local command-line access restored:

dispatch auth wallet --private-key-path ~/.config/dispatch/wallet.key

Claim Into a Web Account

Use the web claim path when you are already signed in with email and want the wallet-funded inbox attached to that Dispatch account. Choose the x402 claim path, connect the same wallet, and sign the displayed proof message.

Common x402 Mistakes

• Using the transaction hash as the payment id. Use the quote payment_reference.
• Confirming with a different wallet from the payer.
• Trying wallet recovery with a wallet that did not fund or verify the inbox.
• Sending less than the quoted amount.
• Sending to the wrong recipient or asset contract.
• Confirming before the transaction is finalized.
• Using an inline private key that lands in shell history.