Payment Flows
The anatomy of every core Scribe Finance payment flow, one step at a time.
One-time payment (x402 flow)
A one-time payment is pure x402: no account, no prior handshake, no relationship between agent and service before the first request lands.
Agent Service API Scribe Finance Facilitator Robinhood Chain
| | | |
|-- 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 entire sequence collapses to a single agent.pay() call; the SDK drives each step for you.
Subscription signup
A subscription writes a standing authorization to the chain. From that point on, the agent’s requests carry a subscription id instead of a payment. No per-request payment work remains on the agent’s side.
Agent Service API Scribe Finance Facilitator Robinhood Chain
| | | |
|-- 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-ScribeFinance-Sub: <sub.id> | | |
| |-- verify on-chain ------>| |
| |<-- ACTIVE ---------------| |
|<-- 200 OK + data ---------| | |
| | | |
| [30 days later] | | |
| |-- auto-collect --------->| |
| | |-- billing TX ----->|
| | |<-- confirmed ------|
Renewals require nothing from the agent; each billing cycle is collected and written to the chain automatically.
Agent-to-agent payment
Nothing in the protocol distinguishes a human-run service from an agent-run one. A specialist agent can publish a plan, gate its API, and bill orchestrator agents through the same subscription rails: the foundation for economies where agents buy capabilities from each other.
Orchestrator Agent Specialist Agent Robinhood Chain
| | |
|-- POST /analyze (legal doc) ->| |
| | |
|<-- 402 + plan terms ----------| |
| | |
|-- subscribe to specialist --->| |
| |-- create sub TX -------->|
| |<-- confirmed ------------|
| | |
|-- POST /analyze (legal doc) ->| |
| X-ScribeFinance-Sub: <sub.id> | |
|<-- 200 OK + analysis result --| |
| | |
| [monthly] | |
| |-- auto-collect --------->|
| |<-- confirmed ------------|
On the selling side, the specialist uses the Provider SDK exactly as any other service would: publish a plan, stand up the payment gate, collect.
Metered billing flow
For usage-based pricing, the agent subscribes to a plan and attaches an allowance that budgets its metered overage.
Agent Service API
| |
|-- subscribe with overage ->|
| { planId, maxOverage: 20 USDG }
|
| [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 cap is reached, the service returns 402, signaling the agent to either lift its overage ceiling or subscribe to a larger plan.
Error states
| Error | Cause | Resolution |
|---|---|---|
InsufficientFunds |
The agent wallet’s USDG balance is too low | Fund the wallet with USDG |
SubscriptionNotActive |
The subscription is paused or cancelled | Renew it, or subscribe again |
AllowanceExhausted |
The spend cap is fully used | Raise the cap, or wait for the cycle to reset |
InvalidPaymentProof |
The Facilitator declined the proof | The SDK retries automatically; persistent failures warrant a Facilitator status check |
PlanDeprecated |
The plan no longer accepts new subscriptions | Move to the provider’s current plan |