Allowance Engine

x402 facilitator

x402 v1, scheme exact, network solana, asset USDC. The payload is a transaction the session key signed with the facilitator as fee payer; the facilitator adds its signature only after its checks pass.

402 challenge (endpoint to agent)

HTTP/1.1 402
{ "x402Version": 1, "error": "X-PAYMENT header is required",
  "accepts": [{ "scheme": "exact", "network": "solana", "maxAmountRequired": "10000",
    "resource": "https://www.allowanceengine.com/api/x402/quote?mint=So11111111111111111111111111111111111111112",
    "payTo": "<address>", "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "maxTimeoutSeconds": 60, "mimeType": "application/json",
    "extra": { "feePayer": "HAuK2WNDKetKK84tLK6HJC2b2TYGonH2eiqwjMxMVyAG", "facilitator": "https://www.allowanceengine.com/api/x402",
      "relayFeeBps": 50, "feeAccount": "7ar53VLy3cBgywMrP6p5bvn7DMryQ8jEGCdv8Sxrzsf2", "decimals": 6 } }] }

X-PAYMENT (agent to endpoint)

base64(JSON.stringify({ x402Version: 1, scheme: "exact", network: "solana",
  payload: { transaction: "<base64 versioned transaction, signed by the session key>" } }))

The transaction may contain only: SetComputeUnitLimit (at most 100,000) and SetComputeUnitPrice (at most 100,000 micro-lamports), the payment TransferChecked from the arm to payTo's USDC account, the fee TransferChecked to the relay fee account, and one Memo without signers. The fee payer appears in no instruction and no lookup table is allowed, so co-signing can never move the facilitator's SOL or tokens.

Facilitator

Route	Body	Returns
`GET /api/x402/supported`		Kinds, fee payer, asset, relay fee, fee account.
`GET /api/x402/fee?arm=&amount=`		Relay fee for the arm's owner, fee account, fee payer, a recent blockhash.
`POST /api/x402/verify`	`{ paymentPayload, paymentRequirements }`	`{ isValid, invalidReason, payer }`
`POST /api/x402/settle`	same	`{ success, transaction, network, payer, errorReason }`

Verify reads the transaction, checks that the source is one of the eight arm addresses of its owner, that the session key is the arm's delegate with enough budget and balance, that payTo is on the signed allow-list, that amount plus fee fits the day's cap, and that the fee is paid, then simulates it. Settle runs the same checks, reserves the amount against the cap, co-signs, submits and answers once the transaction is confirmed. A signed transaction is settled once.

Accept arm payments on your endpoint

curl -O https://www.allowanceengine.com/sdk/server.mjs

import { paywall } from "./server.mjs";
const gate = paywall({ price: 10000n, payTo: "YourSolanaAddress", facilitator: "https://www.allowanceengine.com/api/x402" });

export async function GET(req) {
  const paid = await gate(req, "One weather report");
  if (paid.response) return paid.response;
  return Response.json({ temp: 21 }, { headers: paid.headers });
}

payTo must already hold a USDC account; the facilitator does not create accounts for payees.

Demo endpoint

GET https://www.allowanceengine.com/api/x402/quote?mint=<mint> (or ?symbol=SOL, JUP, BONK, WIF, JTO, PYTH, RAY, ORCA) costs 0.01 USDC and returns the token's live price from Jupiter.