Skip to main content
This page covers the five Stellar ideas every other page assumes: trustlines, SEP-41 amounts, fee sponsorship, authorization entries, and smart accounts. Read it once and the scheme and role pages read straight through.

​
Trustlines

A Stellar account needs a trustline to a SEP-41 asset before it can hold that asset. The one people forget is the receiver’s: the seller’s payTo must trust the asset before it can be paid.
1

Fund the account

The account needs XLM to exist and to pay for its own trustline entry. The Rail402 CLI generates and funds one from friendbot:
Or fund an existing address in Stellar Lab directly.
2

Add the trustline

Add a trustline to the asset with a changeTrust operation from any Stellar SDK, or build one in Stellar Lab.
3

Get the asset

Get testnet USDC from the Circle faucet. XLM comes from friendbot.
A missing trustline has its own rejection code, so the cause is never a mystery: See the error reference for the full set.

​
SEP-41 tokens and stroop math

Rail402 settles any SEP-41 token, with USDC as the default. SEP-41 is the Stellar token interface, and every SEP-41 asset is reachable from Soroban through its Stellar Asset Contract (SAC). The testnet USDC contract is CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA. Amounts are integers at 7 decimals, called stroops. One USDC is 10000000 atomic units, so 500000 is 0.05 USDC.
Never use floating-point math on an amount. Number("9007199254740993") silently loses precision, and an amount is the one value where that matters. Pass amounts as integer strings and do integer arithmetic. The SDK expects atomic-unit strings; the CLI takes decimals and converts them for you.

​
Fee sponsorship

The facilitator pays the Stellar network fee, so the buyer holds only the payment asset and needs no XLM. It does this by rebuilding the transaction with its own account as the source. /supported advertises this with extra.areFeesSponsored: true, and the flag reflects real runtime configuration. You can confirm sponsorship on chain: for any settlement, the fee is charged to the facilitator, not the buyer.

​
Authorization entries

On Stellar the buyer signs a Soroban authorization entry, not a whole transaction. The entry permits one specific contract call (a transfer(from, to, amount) on the asset’s SAC) and nothing else. The facilitator builds and submits the transaction around it. Each authorization is valid until a specific ledger, signatureExpirationLedger, roughly 12 ledgers (about 60 seconds) by default, derived from the seller’s maxTimeoutSeconds. After that ledger the authorization is dead and the buyer signs a new one. This is the mechanism behind both exact and upto.

​
Smart accounts

A buyer address can be either kind of Stellar account, and the facilitator settles from both:

G keypair

A classic account controlled by an ed25519 keypair. It signs its own authorizations directly.

C contract account

A __check_auth contract account (for example an OpenZeppelin smart account) with a session key and an on-ledger spending policy. Its policy can enforce a budget on the ledger itself.
The facilitator is address-agnostic and settles from both G (keypair) and C (contract) accounts. A contract account’s authorization cross-calls a verifier and a policy, so it costs more in fees than a keypair payment; an operator serving smart-account buyers raises MAX_TRANSACTION_FEE_STROOPS accordingly (see Run the facilitator). A C-account spending policy is what upto composes with to keep an agent inside a budget.

​
Interop

None of the helpers are required to interoperate. A stock, unmodified @x402/* client pays a Rail402 endpoint with no Rail402-specific code, and reads the Bazaar through the same interface it uses for any facilitator. The helpers add ergonomics on top.

​
Next steps

The exact scheme

Auth entries and expiration in the fixed-price flow.

The upto scheme

Ceilings and smart-account spending policies.

The payment loop

The four roles and the full sequence.

Troubleshooting

Trustline and expiration failures, and their fixes.