HomeDocsDemoGitHubnpm install →
DEFI_COPILOT
API Reference

x402 Payment

DeFi Copilot uses the x402 protocol — an open standard for HTTP-native micropayments. Agents pay per call using Stellar USDC, with on-chain settlement verified by a local facilitator.

What is x402?

x402 repurposes the HTTP 402 Payment Required status code to build a machine-native payment protocol. When a client hits a paid endpoint, the server responds with 402 and a payment descriptor. The client builds a Stellar transaction, attaches it as a header, and retries.

No API keys, no OAuth, no subscriptions — payment is authentication.

Payment flow

1
Initial request
Client sends a normal GET request to a paid endpoint. No payment header required on the first attempt.
2
402 response
Server returns HTTP 402 with a JSON body describing the payment requirements — asset, amount, destination wallet, and network.
402 response body
{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "stellar-mainnet",
      "maxAmountRequired": "1000",
      "asset": "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
      "payTo": "GXXXX..."
    }
  ]
}
3
Build and sign transaction
Client builds a Stellar USDC payment transaction (0.001 USDC = 1000 stroops) signed with the agent wallet private key.
4
Attach payment header
The signed transaction is base64-encoded and sent as the x-payment header on the retry request.
retry request
curl https://api.fxjrin.com/defi/yield/best \
  -H "x-payment: <base64-encoded-payment-payload>"
5
Facilitator verification
The local x402 facilitator (port 4022) validates the transaction signature and settles it on the Stellar network.
6
200 OK — data returned
Once settlement is confirmed, the API returns the DeFi intelligence with HTTP 200.

Pricing

/defi/yield/best0.001 USDC1000 stroops
/defi/swap/best0.001 USDC1000 stroops
/healthFREE—
/FREE—

Networks

Testnet

Agent wallet is auto-funded via Friendbot. USDC acquired automatically by swapping XLM. Safe for testing.

STELLAR_NETWORK=testnet
Mainnet

Real USDC payments. Agent wallet is generated but not auto-funded — user must deposit XLM manually.

STELLAR_NETWORK=mainnet

Local facilitator

The x402 facilitator runs locally on port 4022. It validates transaction signatures and confirms on-chain settlement before the API releases the response.

start facilitator
npm run facilitator   # port 4022 npm start            # starts both API (3000) + facilitator (4022)