Add Stellar support

[marcelosalloum]

Description

Note

This PR partially addresses the issue #633

Added basic Stellar blockchain support to the x402 exact scheme, specifically to the typescript packages, enabling users to make payments using Stellar network alongside existing EVM and SVM chains.

The implementation leverages Stellar's SEP-41 token standard for transfers via invokeHostFunction operations (not classic Stellar payment operations), where the client signs the auth entry for the transaction, and the facilitator rebuilds the transaction with their account as source, signs, and submits.

Payment Requirements Format

For Stellar exact scheme payments, the PaymentRequirements format is:

{
  scheme: "exact",
  network: "stellar-testnet" | "stellar",
  resource: "https://api.example.com/resource",
  description: "Description of the protected resource",
  mimeType: "application/json",
  maxTimeoutSeconds: 60,
  maxAmountRequired: "100000",  // Amount in stroops (7 decimal places for USDC)
  payTo: "GCHEI4PQEFJOA27MNZRPQNLGURS6KASW76X5UZCUZIXCOJLKXYCXOR2W",  // Stellar address (G-account or C-account)
  asset: "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",  // SEP-41 token contract address
  extra: {
    maxLedger: "12345678"  // REQUIRED: Maximum ledger number for transaction validity (obtained from facilitator)
  }
}

Note: The extra.maxLedger field is required for Stellar (unlike EVM/Solana where extra is optional). This specifies the maximum ledger number by which the transaction must be included on-chain.

📦 Modified typescript packages

• x402-axios
• x402-fetch
• x402-express
• x402-hono
• x402-next
• facilitator

Examples Updated

The following TypeScript examples now support Stellar:

• examples/typescript/facilitator
• examples/typescript/servers/express
• examples/typescript/clients/axios
• examples/typescript/clients/fetch

Tests

Unit tests

Added comprehensive unit test coverage for the included Stellar components, as well as the modified pieces of code. Run pnpm test from the /typescript directory

Manual tests

Following the running example from README.md, I've executed e2e manual tests to ensure the facilitator, servers and clients are working as expected.

Checklist

• I have formatted and linted my code
• All new and existing tests pass
• My commits are signed (required for merge) -- you may need to rebase if you initially pushed unsigned commits

Known Limitations & Future Work

The following enhancements are planned for future PRs:

• Fee Bump Transactions: Update facilitator to use Stellar's FeeBumpTransaction for higher throughput and more reliable settlement
• E2E Test Coverage: Add Stellar-specific test cases to the e2e folder
• Paywall Integration: Add Stellar-compatible browser wallets (e.g., Freighter, xBull) as paywall options
• MultiNetworkSigner: Extend the multi-network signer interface to include Stellar alongside EVM and Solana

Design Changes

Asset Configuration Refactoring

Introduced a new method getUsdcConfigForNetwork(network: Network) to retrieve USDC configuration for any supported network. This diverges from the previous EVM-centric approach that relied on chainId for asset lookup.

Rationale: Stellar (like Solana) is not an EVM chain and does not have a chainId. The new network-based approach provides a unified interface across all blockchain types (EVM, Solana, and Stellar), simplifying multi-chain asset configuration.

Benefits:

• Consistent API across all network types
• Eliminates EVM-specific assumptions in shared code
• Easier to extend for future non-EVM chains

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1

[vercel]

@marcelosalloum is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.