Agentic Payments on Stellar with x402

x402 revives the long-unused HTTP 402 Payment Required status code as a protocol for machine-to-machine payments: an AI agent or script calls your API, your server replies 402 with payment requirements, the caller pays, and a facilitator verifies and settles that payment so your API never has to run its own blockchain integration.

Blockdaemon runs an x402 facilitator for Stellar, built on top of the Stellar Relayer (Channels) — so payments settle through the same managed infrastructure, without you operating a Stellar signer yourself.

🚧

Warning

Blockdaemon's x402 facilitator is currently available on Stellar testnet only. Mainnet support is planned — contact your Blockdaemon account team if you're evaluating this for production.

1. Who This Guide Is For

This page is for teams that:

• Expose an API that AI agents or automated clients call, and want to charge per request.
• Want to accept Stellar-based stablecoin payments (e.g. USDC) without building settlement logic themselves.
• Are prototyping agentic/x402 payment flows and want a hosted facilitator rather than running their own.

2. How It Fits Together

• Your resource server (the API being paid for) uses an x402 middleware library to require payment and ask the facilitator to verify and settle it.
• The buyer (an agent or client library) signs a payment authorization and retries the request with it attached.
• Blockdaemon's facilitator verifies the payment via Soroban RPC simulation, then delegates actual on-chain settlement to the Stellar Channels relayer — the facilitator itself never holds or submits your funds.

sequenceDiagram
    autonumber
    participant B as Buyer (agent / client)
    participant S as Resource server (your API)
    participant F as Blockdaemon x402 facilitator
    participant C as Stellar Channels relayer
    participant N as Stellar network

    B->>S: GET /weather
    S-->>B: 402 Payment Required (payment requirements)
    B->>B: Sign payment authorization
    B->>S: Retry GET /weather with payment attached
    S->>F: POST /verify
    F->>N: Simulate transaction (Soroban RPC)
    F-->>S: Payment is valid
    S->>F: POST /settle
    F->>C: Submit transaction
    C->>N: Fee-bump and submit
    N-->>C: Confirmed
    C-->>F: Transaction hash
    F-->>S: Settlement result
    S-->>B: 200 OK + resource

3. Before You Start

You'll need:

• A Stellar testnet account for your buyer client, funded with testnet XLM (Friendbot) and a testnet USDC trustline/balance (Circle's testnet faucet).
• A recipient (payTo) Stellar address, the account that should receive payment. It must exist on-chain and have a USDC trustline.
• A Blockdaemon API key. The facilitator uses the same self-service API keys as the Stellar Relayer (Channels). Generate one on the testnet endpoint:

curl https://channels-testnet.blockdaemon.tech/gen

{
  "apiKey": "..."
}

Store this key securely — it's shown once and isn't recoverable.

4. Facilitator Endpoint

The facilitator runs on the same domain as the Channels relayer, under the /x402 path. Requests are authenticated with Authorization: Bearer <api-key>, using the key you generated above. The facilitator exposes the routes the x402 protocol expects, appended to the base URL above: /verify, /settle, and /supported.

📘

Info

Facilitator requests count toward the same per-key rate limit as Channels submissions (60 requests per minute). See the Channels guide for details.

5. Integrating as a Seller (Resource Server)

Point your x402 middleware's facilitator client at Blockdaemon's endpoint. This example uses the @x402/express and @x402/core packages:

import express from "express";
import { paymentMiddleware, x402ResourceServer } from "@x402/express";
import { HTTPFacilitatorClient } from "@x402/core/server";
import { ExactStellarScheme } from "@x402/stellar/exact/server";

const facilitator = new HTTPFacilitatorClient({
  url: process.env.FACILITATOR_URL, // https://channels-testnet.blockdaemon.tech/x402
  createAuthHeaders: async () => {
    const h = { Authorization: `Bearer ${process.env.FACILITATOR_API_KEY}` };
    return { verify: h, settle: h, supported: h };
  },
});

const resourceServer = new x402ResourceServer(facilitator)
  .register("stellar:testnet", new ExactStellarScheme());

const app = express();
app.use(paymentMiddleware({
  "GET /weather": {
    accepts: { scheme: "exact", price: "$0.001", network: "stellar:testnet", payTo: process.env.STELLAR_RECIPIENT },
    description: "Current weather data",
  },
}, resourceServer));

app.get("/weather", (_req, res) => res.json({ temp: 21 }));
app.listen(3000);

6. Integrating as a Buyer (Agent / Client)

A buyer signs payments with a Stellar keypair and wraps its HTTP client so 402 responses are paid automatically and retried:

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { createEd25519Signer } from "@x402/stellar";
import { ExactStellarScheme } from "@x402/stellar/exact/client";

const signer = createEd25519Signer(process.env.STELLAR_SECRET_KEY, "stellar:testnet");

const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "stellar:testnet", client: new ExactStellarScheme(signer) }],
});

const res = await fetchWithPayment("https://your-api.example.com/weather");
const data = await res.json();

7. Troubleshooting

unexpected_verify_error on every request

❗️

Important

On a freshly provisioned facilitator, its identity account may not yet exist on-chain, which disables verification until it's funded. This is a Blockdaemon-side setup step — if you see this error against an environment you were told is live, contact Blockdaemon support rather than trying to fund it yourself.

8. Where to Go Next

• Settlement details: payments accepted here settle through Blockdaemon's Stellar Relayer (Channels).
• Learn the protocol: see the x402 specification for the full payment flow, schemes, and network identifiers.
• Planning for mainnet, or need a higher rate limit? Contact your Blockdaemon account team.