x402stellar

name: x402stellar description: x402 HTTP-native payment protocol for AI agents on Stellar. Use when implementing pay-per-use APIs, agent micropayments, or HTTP 402 Payment Required flows with USDC on Stellar/Soroban. license: Apache-2.0 metadata: author: trionlabs version: "1.0.0" x402-sdk-version: "~2.9.0"

x402: HTTP-Native Agent Payments on Stellar

x402 is an open protocol from Coinbase that activates the HTTP 402 "Payment Required" status code for programmatic per-request payments. On Stellar, it uses Soroban authorization entries and USDC for near-instant micropayments — ideal for AI agent commerce.

Companion skills: /stellar-dev for Soroban transaction patterns and Freighter integration. /8004stellar for agent identity and reputation.

Alternative protocol: See /stellar-dev → mpp.md for MPP (Machine Payments Protocol) — direct on-chain settlement without a facilitator, plus payment channels for high-frequency agents. Agents can support both x402 and MPP simultaneously.

EVM version: See /x402 for the Celo equivalent using thirdweb.

When to Use

• Implementing pay-per-use API endpoints on Stellar
• Building AI agents that pay for services autonomously
• Creating micropayment flows for content or data access
• Accepting USDC payments without traditional payment infrastructure

Key Benefits

Installation

npm install @x402/core @x402/express @x402/fetch @x402/stellar @stellar/stellar-sdk

Written against @x402/stellar@~2.9.0. Compatible with @stellar/stellar-sdk@^14.6.1 or @^15.0.1, and @stellar/freighter-api@^6.0.0 (see the troubleshooting table below). The x402 ecosystem is evolving fast — check for breaking changes if using a newer version.

Server Side (Express)

Protect endpoints with paymentMiddlewareFromConfig. The server scheme parses prices and enhances payment requirements — it takes no constructor arguments.

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

const app = express();

app.use(
  paymentMiddlewareFromConfig(
    {
      "GET /my-service": {
        accepts: {
          scheme: "exact",
          price: "$0.01",
          network: "stellar:testnet",
          payTo: "GABC123...YOUR_STELLAR_ADDRESS",
        },
      },
    },
    new HTTPFacilitatorClient({ url: "https://www.x402.org/facilitator" }),
    [{ network: "stellar:testnet", server: new ExactStellarScheme() }],
  ),
);

app.get("/my-service", (_, res) => res.json({ data: "premium content" }));
app.listen(3001);

Key points:

• Route format is "METHOD /path" (e.g., "GET /my-service")
• paymentMiddlewareFromConfig takes 3 args: route config, facilitator client, scheme array
• ExactStellarScheme from /exact/server takes no parameters
• Price is in USD string format ("$0.01")
• payTo is the Stellar address (G...) receiving USDC payments

Using OpenZeppelin Facilitator (mainnet support)

The Coinbase facilitator (x402.org/facilitator) only supports testnet. For mainnet, use OpenZeppelin:

const facilitatorClient = new HTTPFacilitatorClient({
  url: "https://channels.openzeppelin.com/x402/testnet",  // or /x402 for mainnet
  createAuthHeaders: async () => {
    const headers = { Authorization: `Bearer ${process.env.X402_API_KEY}` };
    return { verify: headers, settle: headers, supported: headers };
  },
});

Generate API keys at:

• Testnet: https://channels.openzeppelin.com/testnet/gen
• Mainnet: https://channels.openzeppelin.com/gen

Client Side (Agent — Private Key)

For server-to-server or autonomous agent payments. The flow is: fetch → detect 402 → create payment payload → retry with payment headers.

import { x402Client, x402HTTPClient } from "@x402/fetch";
import { createEd25519Signer } from "@x402/stellar";
import { ExactStellarScheme } from "@x402/stellar/exact/client";

const NETWORK = "stellar:testnet";
const RPC_URL = "https://soroban-testnet.stellar.org";

// Create signer from S-format secret key
const signer = createEd25519Signer(process.env.STELLAR_PRIVATE_KEY!, NETWORK);
const rpcConfig = { url: RPC_URL };

// Register Stellar scheme with client
const client = new x402Client().register(
  "stellar:*",
  new ExactStellarScheme(signer, rpcConfig),
);
const httpClient = new x402HTTPClient(client);

async function fetchPaid(url: string) {
  // 1. First request — get 402
  const firstTry = await fetch(url);
  if (firstTry.status !== 402) return firstTry;

  // 2. Extract payment requirement from headers
  const paymentRequired = httpClient.getPaymentRequiredResponse(
    (name) => firstTry.headers.get(name),
  );

  // 3. Create signed payment payload
  const paymentPayload = await client.createPaymentPayload(paymentRequired);

  // 4. Encode headers and retry
  const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);
  return fetch(url, { headers: paymentHeaders });
}

const response = await fetchPaid("https://api.example.com/my-service");
const data = await response.json();

Key points:

• createEd25519Signer(privateKey, network) — private key is S-format (starts with S)
• ExactStellarScheme from /exact/client takes signer + optional rpcConfig
• The client flow is manual — no auto-retry wrapper for Stellar currently
• Register with "stellar:*" wildcard to handle all Stellar networks
• Network validation: ensure the client's network (e.g. stellar:testnet) matches the server's payTo network — mismatches cause silent settlement failures

Client Side (Browser — Wallet Signing)

x402 browser clients need a ClientStellarSigner — an object with address and signAuthEntry. The signTransaction method is optional for clients (only signAuthEntry is required).

// ClientStellarSigner interface (from @x402/stellar)
type ClientStellarSigner = {
  address: string;
  signAuthEntry: SignAuthEntry;       // Required — signs Soroban auth entries
  signTransaction?: SignTransaction;  // Optional for clients
};

Using Stellar Wallets Kit (recommended)

The official stellar/x402-stellar examples use Stellar Wallets Kit (SWK) which wraps all 6 compatible wallets:

import { StellarWalletsKit } from "@creit.tech/stellar-wallets-kit/sdk";
import type { SignAuthEntry } from "@stellar/stellar-sdk/contract";
import type { ClientStellarSigner } from "@x402/stellar";
import { getNetworkPassphrase } from "@x402/stellar";

function createWalletSigner(
  address: string,
  network: string,
  kit: StellarWalletsKit,
): ClientStellarSigner {
  const signAuthEntry: SignAuthEntry = async (authEntry, opts?) => {
    const result = await kit.signAuthEntry(authEntry, {
      address,
      networkPassphrase: opts?.networkPassphrase || getNetworkPassphrase(network),
    });
    return {
      signedAuthEntry: result.signedAuthEntry,
      signerAddress: result.signerAddress || address,
    };
  };
  return { address, signAuthEntry };
}

Then use with x402 client:

import { x402Client, x402HTTPClient } from "@x402/fetch";
import { ExactStellarScheme } from "@x402/stellar/exact/client";

const walletSigner = createWalletSigner(publicKey, "stellar:testnet", kit);
const client = new x402Client().register(
  "stellar:*",
  new ExactStellarScheme(walletSigner, { url: "https://soroban-testnet.stellar.org" }),
);
const httpClient = new x402HTTPClient(client);

// Same manual flow as agent client: fetch → 402 → createPaymentPayload → retry

Using Freighter directly

If not using SWK, wrap Freighter's signAuthEntry directly. Freighter 6.x uses a default export for CJS compatibility:

import freighterApi from "@stellar/freighter-api";
const { signAuthEntry, getAddress } = freighterApi;
import type { ClientStellarSigner } from "@x402/stellar";

const address = (await getAddress()).address;
const signer: ClientStellarSigner = {
  address,
  signAuthEntry: async (authEntry, opts?) => {
    const result = await signAuthEntry(authEntry, { address });
    return {
      signedAuthEntry: result.signedAuthEntry ?? "",
      signerAddress: result.signerAddress || address,
    };
  },
};

Note: Freighter returns signedAuthEntry: string | null while x402 expects string. Handle the null case. Import pattern: Do NOT use import { signAuthEntry } from "@stellar/freighter-api" — use the default import and destructure. Named imports break CJS bundling.

Compatible wallets

Freighter (browser extension), Albedo, Hana, HOT, Klever, OneKey.

Freighter Mobile does NOT support x402 (lacks auth-entry signing).

Full example

See stellar/x402-stellar/examples/simple-paywall — Express server + React/Vite client with SWK wallet connection.

Note: No Svelte x402 component exists yet. The browser flow is the same regardless of framework — create a ClientStellarSigner, wire it to ExactStellarScheme, handle the 402 → sign → retry flow.

Payment Flow

1. Client: GET /resource
2. Server: 402 + PAYMENT-REQUIRED header (price, network, payTo, scheme)
3. Client: Signs Soroban auth entry via wallet or private key
4. Client: GET /resource + PAYMENT-SIGNATURE header
5. Facilitator: Verifies signature, wraps in fee-bump tx, submits to Stellar
6. Server: 200 + PAYMENT-RESPONSE header (tx hash, settlement status) + resource

HTTP Headers

All payment data lives in headers — response body is reserved for the actual resource.

Facilitators

Facilitator endpoints: /verify, /settle, /supported

Self-hosted: Deploy OpenZeppelin Relayer with x402 Facilitator Plugin.

USDC on Stellar

Important: Stellar USDC uses 7 decimals (not 6 like EVM). 1 USDC = 10,000,000 base units.

Default asset is USDC, but any SEP-41 compliant token is supported.

Network Configuration

Fee Sponsorship

Clients do not need XLM to pay for transactions. The facilitator:

1. Receives the client's signed auth entry
2. Wraps it in a fee-bump transaction
3. Pays the network fee from its own account
4. Submits to Stellar

This removes the cold-start problem for AI agents — they only need USDC, not XLM.

Soroban Auth Details

x402 on Stellar uses Soroban authorization entries to authorize SEP-41 transfer() calls:

• Nonce: Random int64 for replay protection (each nonce valid for one signature lifetime)
• Signature expiry: Ledger sequence number (~12 ledgers / ~60 seconds from creation)
• Auth entry: HashIdPreimageSorobanAuthorization signed by client wallet
• Contract call: transfer(from: Address, to: Address, amount: i128) on USDC contract

The facilitator verifies the auth entry, simulates the transaction, and settles on-chain.

Error Handling

Client errors

async function fetchPaid(url: string) {
  const firstTry = await fetch(url);
  if (firstTry.status !== 402) return firstTry;

  const paymentRequired = httpClient.getPaymentRequiredResponse(
    (name) => firstTry.headers.get(name),
  );

  let paymentPayload;
  try {
    paymentPayload = await client.createPaymentPayload(paymentRequired);
  } catch (err) {
    // Common causes: insufficient USDC balance, RPC unreachable, wallet rejected signing
    throw new Error(`Payment creation failed: ${err instanceof Error ? err.message : err}`);
  }

  const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);
  const paidResponse = await fetch(url, { headers: paymentHeaders });

  if (paidResponse.status === 402) {
    // Payment was rejected by facilitator — signature invalid, expired, or amount mismatch
    const retryRequired = httpClient.getPaymentRequiredResponse(
      (name) => paidResponse.headers.get(name),
    );
    throw new Error(`Payment rejected: ${JSON.stringify(retryRequired)}`);
  }

  return paidResponse;
}

Common error causes

Testing & Local Development

Setup testnet account

# 1. Create keypair (or use Stellar Lab: https://lab.stellar.org/account/create)
# 2. Fund with XLM via Friendbot
curl "https://friendbot.stellar.org?addr=YOUR_PUBLIC_KEY"

# 3. Get testnet USDC from Circle Faucet
#    Go to https://faucet.circle.com → select "Stellar Testnet" → paste public key
#    Gives 20 USDC per address every 2 hours

Important: You must have a USDC trustline before receiving USDC. Stellar Lab's fund page has a trustline button, or set it up programmatically. Without a trustline, USDC transfers will fail silently.

Test with curl

# Trigger 402 response
curl -v http://localhost:3001/my-service
# → HTTP 402 + PAYMENT-REQUIRED header (base64 encoded)

# Decode payment requirement
curl -s http://localhost:3001/my-service -o /dev/null -D - | grep -i payment-required

The PAYMENT-SIGNATURE header requires Soroban auth entry signing — use the client.js script for end-to-end testing rather than curl.

Troubleshooting

Integration with ERC-8004

Combine agent trust (/8004stellar) with payments (/x402stellar):

// 1. Check agent reputation before paying
const summary = await getAgentSummary(agentId);
if (summary.averageScore < 70) throw new Error("Low reputation");

// 2. Pay for service via x402
const response = await fetchPaid(agentServiceUrl);

// 3. Give feedback after service delivery
await giveFeedback(agentId, 90, "starred", agentServiceUrl);

Environment Variables

# Client
STELLAR_PRIVATE_KEY=S...           # Ed25519 secret key (S-format)

# Server (OpenZeppelin facilitator)
X402_API_KEY=your_api_key          # From channels.openzeppelin.com

# Optional
STELLAR_RPC_URL=https://soroban-testnet.stellar.org

Additional Resources

• x402 on Stellar — Stellar Docs
• Quickstart Guide
• Built on Stellar Facilitator
• x402 Protocol Spec
• coinbase/x402 GitHub — Monorepo (Stellar at typescript/packages/mechanisms/stellar/)
• stellar/x402-stellar — Stellar Foundation examples (paywall, self-hosted facilitator)
• OpenZeppelin Facilitator Plugin
• Signing Soroban Invocations

Related Skills

• stellar-dev — General Stellar/Soroban development (required companion)
• 8004stellar — ERC-8004 Agent Trust Protocol on Stellar
• x402 — x402 on Celo (EVM version)