Payment Flows
Walkthroughs of each core HoodLayer payment flow, step by step.
One-time payment (x402 flow)
One-time payments follow the x402 specification. The agent and the service don’t need any prior relationship.
Agent Service API HoodLayer 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 ---------| | |
One call to agent.pay() and the SDK takes care of every step above.
Subscription signup
Subscribing sets up a persistent authorization on-chain. Once signup completes, future requests skip the payment flow entirely from the agent’s side.
Agent Service API HoodLayer 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-HoodLayer-Sub: <sub.id> | | |
| |-- verify on-chain ------>| |
| |<-- ACTIVE ---------------| |
|<-- 200 OK + data ---------| | |
| | | |
| [30 days later] | | |
| |-- auto-collect --------->| |
| | |-- billing TX ----->|
| | |<-- confirmed ------|
Renewal runs on its own; the agent doesn’t have to lift a finger.
Agent-to-agent payment
A specialist agent can sell its capabilities to orchestrator agents over the same subscription infrastructure. That opens the door to multi-agent economic networks in which agents pay each other for services.
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-HoodLayer-Sub: <sub.id> | |
|<-- 200 OK + analysis result --| |
| | |
| [monthly] | |
| |-- auto-collect --------->|
| |<-- confirmed ------------|
Code-wise, the specialist agent creates a plan and wires up the payment gate with the Provider SDK, the same way a human-operated service would.
Metered billing flow
Usage-based billing works by having the agent subscribe to a plan that carries 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) --|
Once the allowance cap is hit, the service answers with a 402 that prompts the agent to raise the overage limit or move up to a bigger plan.
Error states
| Error | Cause | Resolution |
|---|---|---|
InsufficientFunds |
Not enough USDC in the agent wallet | Add USDC to the wallet |
SubscriptionNotActive |
The subscription was paused or cancelled | Resubscribe, or renew it |
AllowanceExhausted |
The spend cap has been hit | Raise the cap or wait for the cycle to reset |
InvalidPaymentProof |
The Facilitator rejected the proof | The SDK retries on its own; if it keeps failing, check Facilitator status |
PlanDeprecated |
The agent tried subscribing to a deprecated plan | Switch to the provider’s current plan |