Skip to content
Unibase Docs

API Reference

The Unibase Pay facilitator implements the x402 verify/settle interface. A resource server declares a price, the client signs a payment payload, and the facilitator checks it and settles it on-chain.

Base URL

Section titled “Base URL”
https://api.x402.unibase.com/v2

The bare base URL returns 404 — it is a prefix you append an endpoint to.

V1 is no longer served. https://api.x402.unibase.com/v1 returns 404 on every path. Migrate to V2; the exact scheme behaves the same.

Endpoints

Section titled “Endpoints”
Method Endpoint Description
POST /verify Check a payment payload without settling it
POST /settle Settle a payment on-chain
GET /supported Scheme and network pairs this facilitator serves

/verify and /settle are POST only — a GET returns 405. There is no /health endpoint; use GET /supported as a liveness probe.

GET /supported

Section titled “GET /supported”

Returns every scheme/network pair the facilitator accepts. This is the authoritative list — prefer reading it at runtime over hardcoding the table below.

Terminal window
curl https://api.x402.unibase.com/v2/supported
{
  "kinds": [
    { "x402Version": 2, "scheme": "exact", "network": "eip155:56" },
    {
      "x402Version": 2,
      "scheme": "upto",
      "network": "eip155:56",
      "extra": { "facilitatorAddress": "0x2cFf062a030f148853aA1c8c12d680B9860Ef041" }
    },
    { "x402Version": 2, "scheme": "batch-settlement", "network": "eip155:56" }
  ]
}

Networks use CAIP-2 identifiers (eip155:<chainId>).

POST /verify and POST /settle

Section titled “POST /verify and POST /settle”

Both take the same envelope:

{
  "paymentPayload": {
    "x402Version": 2,
    "scheme": "exact",
    "network": "eip155:56",
    "payload": { }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "eip155:56",
    "asset": "0x…",
    "payTo": "0x…",
    "maxAmountRequired": "1000000",
    "resource": "https://api.example.com/report",
    "maxTimeoutSeconds": 60
  }
}

Note that x402Version belongs inside paymentPayload; a top-level x402Version is ignored and the request fails version detection. The facilitator routes on the scheme and network pair, so both must appear in GET /supported. See x402.org for the payload field specification.

Errors come back as {"error": "<code>: <detail>"} with HTTP 400. The detail is specific enough to debug against — an unroutable pair, for example, lists every registered scheme@network.

Supported Networks

Section titled “Supported Networks”

All six networks expose all three schemes.

Network CAIP-2 Chain ID
BNB Smart Chain eip155:56 56
BSC Testnet eip155:97 97
Base eip155:8453 8453
Base Sepolia eip155:84532 84532
Polygon eip155:137 137
Arbitrum One eip155:42161 42161

Payment Schemes

Section titled “Payment Schemes”
Scheme Since What it does
exact V1 Charge a fixed, known amount. The server declares a price, the client signs for exactly that amount.
upto V2 Authorize a ceiling, settle actual usage. For metered billing — per-token LLM calls, per-second compute — where the final price is unknown when the request starts.
batch-settlement V2 Aggregate many micropayments into one on-chain transaction. Gas is paid once instead of per call, which is what makes sub-cent agent-to-agent payments economical.

The upto scheme advertises the facilitator address that holds the authorization in extra.facilitatorAddress:

0x2cFf062a030f148853aA1c8c12d680B9860Ef041

Assets

Section titled “Assets”
  • ERC-20 tokens via Permit2
  • EIP-3009 assets (gasless transferWithAuthorization)

Permit2 proxy on BNB Smart Chain:

0x98D0E9d6DC5BCd6FBB75b49dCd0204E966732392