agentic-payments

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)	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
• Calling an x402 API from an agent → x402 Buyer in x402.md
• Selling an API, no facilitator dependency → Charge mode in mpp.md
• Agent making many requests per session → Session mode in mpp.md
• Sold an API, now want agents to find it → Discovery in mpp.md
• 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:

Task	File
Sell a paid API via a facilitator (zero-XLM clients), build an x402 buyer agent	x402.md
Facilitator-free per-request payments (Charge) or channel-backed sessions (Session)	mpp.md
Publish an OpenAPI discovery document so agents find your paid API	Discovery
Create/fund testnet accounts, add USDC trustlines, get testnet USDC	Testnet setup (below)
Which USDC address goes where (classic issuer vs SAC)	Two USDC addresses (below)

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 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

   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()); }"
   

2. Fund both with testnet XLM (friendbot)

   curl "https://friendbot.stellar.org?addr=RECIPIENT_G..."
   curl "https://friendbot.stellar.org?addr=PAYER_G..."
   

3. 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:

   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.BASE_FEE,
       networkPassphrase: StellarSdk.Networks.TESTNET,
     })
       .addOperation(StellarSdk.Operation.changeTrust({
         asset: new StellarSdk.Asset("USDC", USDC_ISSUER),
       }))
       .setTimeout(60)
       .build();
     tx.sign(kp);
     return horizon.submitTransaction(tx);
   }
   
   // Repeat for both the recipient secret and the payer secret.
   await addTrustline(process.env.RECIPIENT_SECRET);
   await addTrustline(process.env.PAYER_SECRET);
   

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

4. 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.

Address	Format	Used for
Classic asset issuer	G... (32-byte ed25519 public key)	The issuer of the classic USDC asset; used when adding a trustline (new Asset("USDC", G...))
SAC (Stellar Asset Contract)	C... (32-byte contract address)	The contract the protocol invokes transfer on; used in payment requirements

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).