The x402 API payment flow
The x402 protocol is an open standard that lets AI agents pay for API calls the same way a browser pays for a web page — with a cryptographic receipt attached to the HTTP request. Pay3 implements x402 natively on Stellar, making it possible for your AI to discover and access paid data feeds, tools, and services without any human involvement.1
AI makes an unauthenticated request
Your AI agent sends a normal HTTP request to an API or MCP server — no payment token, no API key. The server checks whether a valid payment proof is attached.
2
Server responds with HTTP 402 Payment Required
The server returns
402 Payment Required with a payment specification: the price, the asset (e.g. USDC), and an optional memo that identifies the resource.3
AI asks Pay3 to execute the payment
The AI passes the 402 details to the Pay3 SDK. Pay3 validates the request against the active session policy before doing anything else.
4
Pay3 signs and submits a Stellar transaction
The SDK uses the session keypair to sign a Stellar payment transaction and submits it to the Stellar network via the Soroban vault or Horizon.
5
Stellar confirms and Pay3 returns a payment proof
Stellar settles the transaction in 3–5 seconds. Pay3 packages the confirmed transaction hash into a signed x402 Payment Proof token and returns it to the AI.
6
AI resends the request with the payment proof
The AI attaches the x402 token as an HTTP header and retries the original request.
7
Server verifies on Stellar and delivers the resource
The API server queries Stellar to confirm the transaction is real, then unlocks the requested data, computation, or tool response.
The transfer flow (direct payments)
When you ask your AI to send funds directly — “pay 5 USDC to John” — it calls thetransfer MCP tool. Here is exactly what happens from that call to the moment the recipient sees the funds.
1
AI calls transfer(recipient, asset, amount, idempotency_key)
The AI invokes the
transfer tool with four arguments: who to pay, which asset, how much, and an idempotency_key — a stable identifier for this specific payment intent.Idempotency keys protect you from duplicate payments. If your AI retries a transfer (e.g. after a timeout) using the same key, Pay3 recognises the duplicate and returns the original result instead of executing a second transaction.
2
MCP server authenticates the token
The Pay3 MCP server validates the
PAY3_MCP_AUTH_TOKEN from the session configuration. If the token is expired, revoked, or malformed, the request is rejected immediately and the AI receives an error.3
Recipient is resolved
Pay3 looks up the recipient string. It can be:
- A verified contact name or alias stored in your Pay3 contacts (e.g.
"John") - A raw Stellar public key (e.g.
GDQP2KPQ…)
4
Policy engine evaluates the transfer
This is the most important step. Pay3 loads the policy snapshot that was attached to the session at creation time and runs the following checks in order:
- Is the asset allowed? (e.g. USDC, XLM)
- Does the amount exceed the per-transaction maximum?
- Does today’s spending plus this amount exceed the daily budget?
- Is the recipient on any blocklist?
- Has the session expired?
5
Policy engine returns a decision
Based on the checks above, the payment lands in one of three states:
6
AUTO_EXECUTE: session key decrypted and transaction submitted
For auto-executed payments, Pay3:
- Decrypts the session keypair stored server-side.
- Constructs a Stellar payment transaction.
- Signs it with the session key and submits it to the Stellar network via the Soroban vault contract or Horizon API.
- Waits for confirmation (typically 3–5 seconds).
7
Budget updated, audit log written, result returned
On success, Pay3 records the spend against today’s budget counter, writes an immutable audit log entry (timestamp, amount, asset, recipient, transaction hash), and returns the result to the AI — including the Stellar transaction hash as cryptographic proof.
Three-level execution model
Every payment decision passes through the same three-outcome engine. Understanding it tells you exactly what your AI can do autonomously, what requires your attention, and what gets blocked entirely.AUTO_EXECUTE
The amount is at or below your policy’s manual approval threshold and all other checks pass. Pay3 executes the transaction immediately on Stellar. Your AI receives a confirmed transaction hash in the same response.
PENDING_APPROVAL
The amount exceeds your approval threshold but does not violate any hard limits. Pay3 queues the payment in your dashboard. You have 2 minutes to approve or reject it before the request expires.
REJECT
The payment violates policy — wrong asset, over daily budget, over per-transaction maximum, or blocked recipient. Pay3 returns a descriptive error to the AI. No transaction is ever attempted on Stellar.
Session key security model
Pay3’s security model is built around one principle: your AI never has access to your private key. Here is how that guarantee is enforced at every layer.1
A temporary session keypair is generated
When you create a session, Pay3 generates a brand-new Stellar keypair (the session key) dedicated to that session. The session private key is encrypted and stored server-side — your primary wallet key is never involved in any AI transaction.
2
The session key is registered on-chain in your Soroban vault
Your Soroban smart account contract receives an
add_session call that records:- The session public key
- The session expiry timestamp
- The per-transaction maximum (from your policy)
- The daily maximum (from your policy)
3
Policy snapshot is attached at session creation
The policy parameters are snapshotted into the session record when you create the session. Changing a policy after session creation does not affect existing sessions — you need to create a new session to pick up updated limits.
4
Every tool call is authenticated by MCP token
The AI presents its
PAY3_MCP_AUTH_TOKEN on every tool call. Pay3 links the token to the session record, verifies it hasn’t been revoked, and loads the associated smart account and policy snapshot.5
Sessions expire automatically
Session keys have a hard expiry baked into the on-chain contract. Once the expiry timestamp passes, the Soroban contract refuses to authorise any further transactions — no backend intervention required.
6
You can revoke all sessions instantly
In the Sessions dashboard, click Revoke next to any session. Pay3 immediately invalidates the MCP token, and the session key is deregistered from your vault contract. Your AI loses payment capability for that session at once.