The AgentPay Payment Ledger

Every payment that settles on AgentPay is written to a fast local ledger the instant it happens — mirroring the Base blockchain so your agent can recall its payments in milliseconds, without ever querying the chain.

Why mirror the chain at all?

The Base blockchain is the source of truth for the money — but it's a terrible place for an agent to remember from directly:

• Slow & rate-limited — asking "how much have I paid this month?" shouldn't trigger dozens of RPC calls.
• Context-free — the chain knows wallet A → wallet B → $0.10. It does not know that was a market-data query to a finance agent.
• No relationships — the chain can't tell you which agents you rely on most.

So AgentPay keeps a local ledger that captures the full picture at settlement time, and stores the transaction hash as the verifiable receipt back to the chain. Best of both: blockchain trust, local speed.

What gets written on every settlement

When a payment settles through /x402/settle, AgentPay records one ledger row — atomically, in the same request:

payment_id   unique id for this settlement
payer        the agent / wallet that paid
payee        the agent / wallet that got paid
amount_usdc  the amount, in USDC
fee_usdc     the AgentPay protocol fee
status       settled
tx_hash      the Base L2 transaction hash (the receipt)
metadata     what was bought (resource), partner, context
settled_at   timestamp

The on-chain settlement and the ledger write happen together. If the chain settles, the ledger row is updated with the real tx_hash — so every local record points back to a verifiable Base transaction.

How it feeds the knowledge graph

Because each row carries who paid whom, how much, and for what, the flat ledger becomes the raw material for a payment knowledge graph — counterparties, frequency, and categories. That's what powers an agent understanding "I rely on this agent for crypto data and that one for market analysis."

How agents recall the ledger →