x402 Integration Guide

Build agent-powered payment flows on Base.

What is x402?

x402 is the payment layer BaseZap uses to expose paid agent capabilities over HTTP. Agents can pay for a successful API response with USDC on Base instead of relying on subscriptions or application accounts.

BaseZap currently exposes paid endpoints for Farcaster identity resolution and unsigned USDC tip calldata.

Agent endpoints

1. Resolve a Farcaster user

Resolve a Farcaster username or FID to a verified wallet address on Base.

GET /api/agent/resolve-username?username=afifarioss

Price: $0.001 USDC per successful request.

2. Build tip transaction calldata

Build unsigned USDC transfer calldata for a BaseZap tip. The response contains the creator transfer and the BaseZap platform fee transfer.

POST /api/agent/build-tip-calldata

{
  "recipient": "0x...",
  "amount_usdc": 1
}

Price: $0.001 USDC per successful request.

Calling a paid endpoint

An agent sends its request normally. The x402 flow handles payment authorization and settlement when the endpoint returns successfully.

const response = await fetch(
  "https://basefarcaster.vercel.app/api/agent/resolve-username?username=afifarioss"
);

const result = await response.json();

Failed lookups return an error response and are not settled as successful x402 requests.

Tip economics

The x402 API fee and the tip amount are separate. The $0.001 x402 charge pays for access to the paid agent endpoint. A tip generated through BaseZap follows BaseZap's tipping fee model.

Standard creator share:98%

Standard platform fee:2%

Qualifying $ZAP holders:0% platform fee

The current agent calldata endpoint generates the standard 2% platform-fee split. The $ZAP holder benefit is supported by BaseZap's fee calculation for qualifying holders.

Non-custodial by design

✓Agent endpoints do not hold user private keys
✓Tip calldata is returned unsigned
✓Transactions are not broadcast by the calldata endpoint
✓Payments settle on Base

Best Practices

✓Validate recipient addresses before building transactions
✓Use the returned calldata without modifying its destination or amount
✓Handle unsuccessful API responses before relying on results
✓Keep private keys in the agent's own wallet infrastructure

Ready to build?

Use BaseZap's agent endpoints to discover Farcaster users and construct Base-native payment flows.

Explore Agent APIs →