x402 integration

Prerequisites

• A payzum merchant account with at least one merchant configured.
• A public HTTPS URL for the API you want to monetize (private/loopback addresses are not allowed).
• A wallet address on Base to receive USDC payments.
• For mainnet settlement: a Coinbase Developer Platform (CDP) API key. For development: no additional setup needed.

Step 1: Configure the settlement facilitator

Before creating protected routes, choose how payments will settle. Navigate to your merchant's API for Agents page in the dashboard and open the Settlement panel.

Coinbase (CDP) — mainnet

Enter your CDP API key ID and secret. These are available at portal.cdp.coinbase.com → API keys. The secret is stored encrypted; payzum uses it to generate a short-lived EdDSA JWT per transaction for the Coinbase facilitator API. Gas and per-transaction fees are billed to your CDP account.

Testnet — free

Select Testnet to use the free public facilitator on Base Sepolia. No real funds move. This is the recommended choice during development and testing.

Step 2: Create a protected route

In the API for Agents panel, click New monetized endpoint and fill in the form:

| Field | Description | |---|---| | Path | A URL-safe slug, e.g. market-data. Agents will call this path on payzum. | | Your API URL | The origin URL payzum forwards paid requests to (public HTTPS only). | | Price per call (USDC) | Decimal amount, e.g. 0.01. Entered in whole USDC; stored as atomic units internally. | | Receive USDC at (Base) | Your EVM wallet address on Base where settlement lands. |

Optional: upstream authentication

If your origin API requires a credential, payzum can inject it on every forwarded request. Choose the authentication type in the form:

• None — origin is open or trusts payzum's source IP.
• Bearer token — payzum adds Authorization: Bearer <token>.
• API key header — payzum adds a custom header (X-API-Key by default) with your value.
• Basic auth — payzum adds an Authorization: Basic header.

Upstream credentials are stored encrypted. Agents never see them.

Free quota per day

Routes include a configurable daily free quota. Calls within the quota are forwarded without requiring payment. The default is 0 (every call requires payment).

Step 3: Make your endpoint discoverable (optional)

Toggle List in the discovery catalog to publish the route so agents can find it. When enabled, additional fields appear:

| Field | Description | |---|---| | Title | Short name agents see in the catalog, up to 120 characters. | | Description | What the endpoint does and what input it expects. Agents search this text. | | Category | One of: data, finance, ai, media, tools, web, other. | | Method | The HTTP method agents should use: GET, POST, PUT, PATCH, or DELETE. |

Input and output schemas (JSON Schema)

Two optional JSON Schema fields let you publish a machine-readable contract for agents:

• Input parameters — describes the query or body parameters agents must send. This is surfaced as the outputSchema.input field in the x402 payment requirements, which the Bazaar and x402-aware clients read to build the correct call.
• Response shape — describes what your endpoint returns, so agents know how to parse the result. This is surfaced as outputSchema.output.

Example input schema for a price endpoint:

{
  "type": "object",
  "properties": {
    "symbol": { "type": "string", "description": "Token symbol, e.g. ETH" }
  },
  "required": ["symbol"]
}

Both fields are optional. If you omit them, the route advertises no machine-readable parameter contract — agents can still discover and pay for it, but they must infer the call shape from the title and description.

How the payment handshake works

Once a route is live, the flow for each agent request is:

1. Agent calls the payzum URL — the public slug on payzum (e.g. https://merchant.payzum.com/v1/x402/<merchant-id>/<slug>). No API key or token is required.
2. payzum returns 402 — the response body contains the x402 payment requirements: scheme (exact), network (base), asset address, price in atomic USDC, your wallet address, and any I/O schema.
3. Agent pays — the agent constructs an EIP-3009 transferWithAuthorization over USDC, signs it with its own wallet, and retries the request with the signed payload in the X-PAYMENT header.
4. Facilitator verifies and settles — payzum sends the payment payload to the configured facilitator (/verify, then /settle). On success, the facilitator broadcasts the on-chain transfer.
5. Request forwarded — payzum proxies the original request to your origin URL, injects any upstream auth, and returns the response to the agent.

The discovery catalog

Agents can fetch a list of all discoverable routes by querying the discovery endpoint for your merchant. The response follows the x402 discovery list format: each item includes the resource URL, payment requirements (so the agent knows the exact price before calling), and the metadata fields you configured.

Deny list

You can configure a list of wallet addresses that are blocked from paying for a route. Requests carrying a payment authorization from a denied address are rejected before the facilitator is called.

Testing locally

Set the facilitator to Testnet in the dashboard. The testnet mode uses the free public x402.org facilitator on Base Sepolia — real network settlement occurs, but with testnet funds only (no real USDC moves). This lets you exercise the full 402 → verify → settle → proxy path against an actual facilitator service.

Route management

Existing routes can be edited or deleted from the dashboard. Deleting a route stops agents from being able to pay for it immediately. Pausing a route (unchecking Live) keeps the configuration but stops accepting payments.

Next steps

• Read the x402 overview for a conceptual introduction and the settlement asset details.
• For webhook events related to x402 settlements, refer to the Webhooks overview.