Payment Flows
Step-by-step walkthroughs of the core payment flows in Recur Protocol.
One-time payment (x402 flow)
The one-time payment flow follows the x402 specification. No prior relationship between the agent and the service is required.
Agent Service API Recur Facilitator Solana
| | | |
|-- GET /v1/data ---------->| | |
| | | |
|<-- 402 + payment terms ---| | |
| { scheme, amount, | | |
| token, payTo, memo } | | |
| | | |
|-- POST /authorize ----------------------------------------->| |
| { signedPayment } | | |
| | |-- submit TX ------->|
| | | |
| | |<-- TX confirmed ----|
|<-- payment proof ---------|--------------------------| |
| | | |
|-- GET /v1/data ---------->| | |
| X-PAYMENT: <proof> | | |
| |-- verify proof --------->| |
| |<-- valid ----------------| |
|<-- 200 OK + data ---------| | |
The SDK handles all of this in a single agent.pay() call.
Subscription signup
The subscription flow creates a persistent on-chain authorization. After signup, the agent no longer needs to interact with the payment flow for future requests.
Agent Service API Recur Facilitator Solana
| | | |
|-- GET /v1/data ---------->| | |
| | | |
|<-- 402 + plan terms ------| | |
| { planId, amount, | | |
| interval, token } | | |
| | | |
|-- agent.subscribe({ planId }) -------------------> | |
| (SDK creates subscription account on-chain) | |
| |-- create sub TX -->|
| |-- first billing -->|
| |<-- confirmed ------|
|<-- subscription.id -----------------------------------| |
| | | |
|-- GET /v1/data ---------->| | |
| X-Recur-Sub: <sub.id> | | |
| |-- verify on-chain ------>| |
| |<-- ACTIVE ---------------| |
|<-- 200 OK + data ---------| | |
| | | |
| [30 days later] | | |
| |-- auto-collect --------->| |
| | |-- billing TX ----->|
| | |<-- confirmed ------|
Auto-renewal happens without any action from the agent.
Agent-to-agent payment
Specialized agents can sell capabilities to orchestrator agents using the same subscription infrastructure. This enables multi-agent economic networks where agents pay each other for services.
Orchestrator Agent Specialist Agent Solana
| | |
|-- POST /analyze (legal doc) ->| |
| | |
|<-- 402 + plan terms ----------| |
| | |
|-- subscribe to specialist --->| |
| |-- create sub TX -------->|
| |<-- confirmed ------------|
| | |
|-- POST /analyze (legal doc) ->| |
| X-Recur-Sub: <sub.id> | |
|<-- 200 OK + analysis result --| |
| | |
| [monthly] | |
| |-- auto-collect --------->|
| |<-- confirmed ------------|
From a code perspective, the specialist agent uses the Provider SDK to create a plan and add the payment gate, exactly as a human-operated service would.
Metered billing flow
For usage-based billing, an agent subscribes to a plan that includes an allowance for metered overage.
Agent Service API
| |
|-- subscribe with overage ->|
| { planId, maxOverage: 20 USDC }
|
| [creates Subscription + Allowance on-chain]
|
|-- POST /v1/process ------->|
|<-- 200 OK (1k tokens used) |
| |-- deductAllowance(500_000)
|
|-- POST /v1/process ------->|
|<-- 200 OK (2k tokens used) |
| |-- deductAllowance(1_000_000)
|
| [allowance exhausted] |
| |
|-- POST /v1/process ------->|
|<-- 402 (overage cap hit) --|
When the allowance cap is reached, the service returns a 402 response with a prompt to increase the overage limit or upgrade the plan.
Error states
| Error | Cause | Resolution |
|---|---|---|
InsufficientFunds |
Agent wallet lacks USDC | Top up USDC balance |
SubscriptionNotActive |
Subscription is paused or cancelled | Renew or resubscribe |
AllowanceExhausted |
Spend cap reached | Increase cap or wait for cycle reset |
InvalidPaymentProof |
Proof rejected by Facilitator | SDK retries automatically; if persistent, check Facilitator status |
PlanDeprecated |
Agent tried to subscribe to a deprecated plan | Use the provider’s current plan |