Payments

Agents need a positive prepaid balance to create streams, clips, DVR recordings, and VOD uploads. Two funding methods are available: x402 (inline, instant) and crypto deposits (on-chain transfer).

x402 Protocol

x402 enables gasless USDC payments using EIP-3009 transferWithAuthorization. The agent signs a transfer authorization off-chain; FrameWorks submits it on-chain and pays the gas.

Flow

Agent calls a billable tool (e.g., create_stream) with insufficient balance.
Server returns an INSUFFICIENT_BALANCE error with x402_accepts payment options.
Agent signs an EIP-3009 authorization for the required amount.
Agent retries with the X-PAYMENT header containing the base64-encoded signed payload.
Server verifies the signature, submits the transaction on-chain, and credits the balance.
The original operation proceeds.

For browser-based integrations, MCP and GraphQL are CORS-readable public protocol surfaces. JavaScript clients can make the actual unauthenticated API request, receive the 402 response body, sign the payment authorization, and retry with X-PAYMENT.

Payment Options

Call get_payment_options (public, no auth required) to get the platform’s payment address and supported networks:

{
  "x402_version": 1,
  "options": [
    {
      "network": "base",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "asset_symbol": "USDC",
      "pay_to": "0x..."
    },
    {
      "network": "arbitrum",
      "asset": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      "asset_symbol": "USDC",
      "pay_to": "0x..."
    }
  ]
}

X-PAYMENT Header

The X-PAYMENT header contains a base64-encoded JSON payload:

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "base",
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0x<your-wallet>",
      "to": "0x<payTo-from-payment-options>",
      "value": "1000000",
      "validAfter": "0",
      "validBefore": "1735689600",
      "nonce": "0x..."
    }
  }
}

PAYMENT-SIGNATURE is also accepted as a header name.

Supported Networks

Network	Chain ID	USDC Contract
Base	8453	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
Arbitrum	42161	`0xaf88d065e77c8cC2239327C5EDb3A432268e5831`

Crypto Deposits

For non-x402 prepaid top-ups, use the deposit flow:

Call topup_balance with amount_cents and asset: "ETH" or "USDC".
The response is a locked-rate quote: a deposit address plus the exact expected_amount_token to send (e.g. 0.01515 ETH), the quoted_price_usd it was locked at (Chainlink for ETH; 1:1 for USDC), and a 24h expires_at.
Send exactly the quoted amount on-chain.
Call check_topup to follow the lifecycle: pending → confirming → completed.
Once confirmed, the balance is credited at the locked rate (received_token × quoted_price_usd), so you get exactly what was quoted regardless of price drift inside the 24h TTL.

LPT is not supported as a top-up asset. Chainlink doesn’t publish an official LPT/USD aggregator, so topup_balance rejects asset: "LPT".

Preflight Errors

Billable MCP tools validate positive prepaid balance before executing. Account status can also report billing detail blockers; x402 settlement enforces billing details for payments of €100 or more. When requirements aren’t met, the error includes resolution guidance:

Missing billing details:

{
  "code": "BILLING_DETAILS_MISSING",
  "message": "Billing details required before any payments",
  "resolution": "Call update_billing_details with address_line1, city, postal_code, country",
  "tool": "update_billing_details",
  "required_fields": ["address_line1", "city", "postal_code", "country"]
}

Insufficient balance:

{
  "code": "INSUFFICIENT_BALANCE",
  "message": "Balance is 0 cents. Top up required to perform billable operations.",
  "resolution": "Call topup_balance tool to add credits, OR pay via x402",
  "tool": "topup_balance",
  "x402_accepts": [
    { "network": "base", "asset": "USDC", "pay_to": "0x...", "description": "USDC on Base" },
    { "network": "arbitrum", "asset": "USDC", "pay_to": "0x...", "description": "USDC on Arbitrum" }
  ]
}

Cost Awareness

Prepaid usage deductions can move an account toward zero or negative balance. Monitor via the billing://balance resource:

Field	Description
`balance_cents`	Current balance
`drain_rate_cents_per_hour`	Recent rated spend rate, when available
`estimated_hours_left`	Time until depletion
`live_metrics`	Current operational usage context

At zero or below, prepaid accounts are blocked from new billable operations unless the request is settled with x402. If the balance drops below -€10, Purser suspends the tenant and asks Commodore/Foghorn to terminate active streams and sessions. Top up proactively.