Agentic Payments: x402 + MPP

Two complementary protocols for AI-agent and machine-to-machine payments on Stellar. Pick based on who depends on whom and how often the agent pays.

Quick decision

| | x402 | MPP Charge | MPP Session | |--|------|------------|-------------| | Per-request on-chain tx? | Yes (via facilitator) | Yes (SAC) | No (off-chain commits) | | Needs facilitator? | Yes — hosted or your own ([options](x402.md#facilitator-options)) | No | No | | Client needs XLM? | No (fees sponsored) | Optional (feePayer) | Yes | | Setup complexity | Low | Low | Medium (deploy contract first) | | Best for | Quickest setup, fee-free clients | No third-party dep | High-frequency agents |

• Selling an API, want zero-XLM clients → x402 Seller in [x402.md](x402.md)
• Calling an x402 API from an agent → x402 Buyer in [x402.md](x402.md)
• Selling an API, no facilitator dependency → Charge mode in [mpp.md](mpp.md)
• Agent making many requests per session → Session mode in [mpp.md](mpp.md)
• Sold an API, now want agents to find it → Discovery in [mpp.md](mpp.md#discovery-let-agents-find-your-paid-api)
• Unsure → x402 (lowest friction to get started)

All protocols use USDC (SEP-41 SAC) by default; stellar:testnet / stellar:pubnet CAIP-2 network IDs.

Read the file that matches the task

This file carries the decision table, the shared testnet account setup, and the USDC address reference. The protocol playbooks live alongside it:

Related skills

• The SACs the protocols call → ../smart-contracts/SKILL.md
• USDC and other classic assets → ../assets/SKILL.md
• Wallets and signing in the buyer client → ../dapp/SKILL.md
• RPC simulation / submission patterns → ../data/SKILL.md
• SEP-41 (token interface) and related standards → ../standards/SKILL.md

Testnet setup (shared)

Both protocols need the same base setup: a client/payer account (signs and pays from a USDC balance) and a server/recipient account. Both need a USDC trustline.

One step of this shared setup is web-only (Captcha) and cannot be scripted: the Circle USDC faucet. The rest of it can be automated — [x402.md](x402.md) ships a setup.js that does steps 1–3 and writes a starter .env. (Outside this setup, the OZ Channels facilitator that x402.md configures has its own web-only key generator. Each facilitator sets its own auth requirement — the x402.org one needs none — and MPP needs no third party at all.)

1. Generate two keypairs

``bash node -e "const { Keypair } = require('@stellar/stellar-sdk'); for (const n of ['RECIPIENT','PAYER']) { const k = Keypair.random(); console.log(n, k.publicKey(), k.secret()); }" ``

1. Fund both with testnet XLM (friendbot)

``bash curl "https://friendbot.stellar.org?addr=RECIPIENTG..." curl "https://friendbot.stellar.org?addr=PAYERG..." ``

1. Add a USDC trustline to BOTH accounts — open Stellar Lab and add a USDC trustline to each G..., or run via SDK for each keypair:

```js import * as StellarSdk from "@stellar/stellar-sdk";

const horizon = new StellarSdk.Horizon.Server("https://horizon-testnet.stellar.org";); // Circle's classic USDC issuer on Stellar testnet const USDC_ISSUER = "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5";

async function addTrustline(secret) { const kp = StellarSdk.Keypair.fromSecret(secret); const acc = await horizon.loadAccount(kp.publicKey()); const tx = new StellarSdk.TransactionBuilder(acc, { fee: StellarSdk.BASEFEE, networkPassphrase: StellarSdk.Networks.TESTNET, }) .addOperation(StellarSdk.Operation.changeTrust({ asset: new StellarSdk.Asset("USDC", USDCISSUER), })) .setTimeout(60) .build(); tx.sign(kp); return horizon.submitTransaction(tx); }

// Repeat for both the recipient secret and the payer secret. await addTrustline(process.env.RECIPIENTSECRET); await addTrustline(process.env.PAYERSECRET); ```

Without a trustline on the recipient, the SAC transfer settles into nothing and the request fails with opnotrust.

1. Fund the PAYER with testnet USDC — open the Circle testnet faucet, select Stellar testnet, paste the payer's G.... Web Captcha; no API.

Two USDC addresses (don't confuse them)

USDC on Stellar has two addresses, used in different places. Mixing them up is a common stumble.

Use the exported constants instead of hard-coding when possible:

import { USDC_TESTNET_ADDRESS, USDC_PUBNET_ADDRESS } from "@x402/stellar";
// USDC_TESTNET_ADDRESS = "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA"
// USDC_PUBNET_ADDRESS  = "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75"

x402's payTo route config and MPP's recipient are always a classic account (G...). The SAC address only appears where the config names the settlement asset (x402's custom asset price config, MPP's currency).