An AI agent pays for an API response. Its wallet broadcasts the transaction, the network includes it, and the payment service reports progress. Yet the API still needs to decide whether to release the result.
That decision cannot be delegated to the word “onchain.” Transaction submission, network inclusion, application acceptance, service delivery, bridge completion, and stronger finality are different events. They may occur seconds, minutes, or much longer apart, and any one of them can fail while the others succeed.
Onchain payment infrastructure for AI agents therefore needs two synchronized state systems. The chain or payment rail records value movement. The application records the quote, identity context, authorization, delivery, and remedy. Wallets, x402, and identity layers connect the two, but a confirmation policy and reconciliation process determine when machine payment becomes completed commerce.
Onchain Payment Creates Two Sources Of Truth
The first source is the commerce ledger. It answers what the buyer intended to purchase and what the merchant owes in return.
The second is the onchain ledger. It answers what transaction or contract state the network observed under its own rules.
Commerce state | Onchain state |
|---|---|
agent and merchant identity | payer and destination addresses |
resource, quote, and expiry | transaction payload and amount |
spending-policy decision | signature, nonce, and sender authority |
merchant acceptance rule | inclusion and confirmation evidence |
delivery status | transfer or contract-event status |
credit or refund obligation | refund or reversal transaction |
Neither ledger can replace the other. A chain can show that value moved without knowing whether an API returned useful data. An application can mark an order paid based on a callback that later proves incomplete or mismatched unless it retains authoritative payment evidence.
The platform must correlate them with stable identifiers. Every quote, wallet operation, payment attempt, transaction, delivery, and remedy should point back to one purchase. If a retry creates a new transaction, it must remain clear whether that transaction replaces, duplicates, or supplements the first attempt.
This dual-ledger model is the foundation for settlement operations. It makes disagreement visible instead of forcing every event into one success field.
Start With The Merchant's Acceptance Rule
Developers often choose a wallet and payment SDK before deciding what payment state is sufficient to deliver the product. That reverses the dependency.
The merchant should define acceptance from the product's risk and reversibility:
What value is at risk?
Can the resource be revoked after delivery?
Is the result costly to compute?
Is inventory scarce?
Can the buyer tolerate delayed delivery?
Can the merchant refund or issue credit if delivery fails?
What network, scheme, facilitator, and asset are accepted?
A low-cost, repeatable API response may use an earlier accepted state than a scarce digital asset or an irreversible high-value operation. The choice is not simply speed versus safety. Waiting longer can reduce some settlement uncertainty while increasing latency, timeout risk, and poor agent behavior such as premature retries.
Express acceptance as a policy, not an implicit assumption inside a callback handler. A useful rule names the payment scheme, network, asset, amount band, required observed state, expiry handling, and escalation path.
The output should be one of several explicit decisions: deliver, wait, reject, reconcile, or require approval. “Not delivered yet” should not automatically mean “pay again.”
Translate x402 Terms Into Deterministic Transaction Intent
x402 lets a server express payment requirements at the HTTP request layer. An agent requests a resource, receives 402 Payment Required with supported terms, selects a valid option, prepares payment, and retries with payment evidence.
Before any onchain action, the selected requirement must become a deterministic transaction intent. Bind:
the protected resource or merchant order;
amount, asset, network, and scheme;
merchant destination;
quote version and expiration;
payer and task identifiers;
unique attempt or replay boundary;
permitted fees and execution behavior;
the acceptance policy that will govern delivery.
The intent is the handoff from commerce state to onchain execution. The wallet signs the resulting payload, not the original natural-language prompt. If the payment requirement changes materially, the system should create a new intent and re-evaluate policy.
Retain the original x402 requirement and the selected option. They explain why the transaction exists. A transaction decoded from chain data may reveal destination and amount but not the API route, product version, quote expiry, or service promise.
x402 is an open protocol rather than a GOAT-exclusive payment format. GOAT Network includes x402 in its agent infrastructure, where HTTP payment requirements can connect to AgentKit-controlled actions and supported onchain workflows. The application still owns acceptance and delivery.
Bind Identity Before Value Leaves The Wallet
Onchain addresses are necessary for execution, but an address alone is a weak commercial counterparty model. The agent needs to know which service or agent controls the endpoint, which destination it advertises, and which trust signals were considered.
ERC-8004 provides Identity, Reputation, and Validation registries for agents. Those registries can support discovery and policy by resolving an agent record, controller, service metadata, and contextual trust signals.
The identity check should happen before the payment intent reaches the wallet. Compare the endpoint, merchant identity, and payment destination. If the quote sends funds somewhere that does not match the evaluated merchant context, stop and require a fresh resolution or explicit approval.
Store the identity snapshot used for the decision. Agent metadata, controllers, service endpoints, and reputation can change after payment. Historical explanation requires the version or observation time, not only the latest record.
Identity is not a guarantee. Registration proves neither service quality nor honesty. Reputation can be sparse, contextual, manipulated, or stale. Validation may cover one capability rather than the current transaction. The policy should treat identity signals as inputs and state which missing or changed signals block payment.
GOAT Network's integration of ERC-8004 with agent tooling is relevant here because identity actions and payment actions can participate in the same workflow. The developer must still define how identity evidence binds to destination and authorization.
Wallet Policy Controls Entry Into The Chain
Once signed and broadcast, an onchain action can be difficult or impossible to reverse. The wallet boundary is the last place to enforce the complete intent before value enters the network.
The wallet should receive a typed action plus a policy reference. It should verify the signer scope, amount, destination, asset, network, nonce, expiry, and task authority. Controls can include per-payment limits, cumulative budgets, destination allowlists, asset restrictions, contract-method permissions, and human approval thresholds.
The wallet record needs more than a transaction hash. Preserve:
exact signed payload;
signer and account;
network and nonce;
policy decision reference;
signature or authorization object;
submission attempt and timestamp;
replacement or cancellation relationship;
structured denial or error.
Do not let the model bypass policy by reformulating the same action. Controls should operate on normalized transaction fields and cumulative state, not only prompt text.
GOAT Network AgentKit documents wallet and onchain actions alongside policies, input validation, retries, idempotency, timeout handling, and risk levels. Those runtime controls can support bounded payment execution. They do not remove the need to configure custody, budgets, merchant rules, or approvals for the application.
Track The Transaction Beyond Broadcast
Broadcast is an attempt, not settlement. The transaction can remain pending, be replaced, fail execution, be dropped, or become difficult to query through one provider.
Model at least these states where the network supports them:
Do not map broadcast to paid. Do not map an RPC timeout to failed. A timeout may leave the system uncertain whether the transaction reached the network. Retrying with a fresh nonce or payment authorization can create duplicate value movement.
The tracker should query by durable transaction and account references. Use more than one observation path where the risk justifies it, but preserve which source reported each status. Indexer lag and RPC disagreement should produce an explicit uncertain state rather than a fabricated consensus.
Contract-based payment flows need execution status and relevant events, not only transaction inclusion. A transaction can be included while the contract call reverts. Event decoding should verify expected contract, asset, destination, amount, and order reference where the scheme provides them.
Use A Confirmation Matrix Instead Of One Settled Flag
One global threshold is rarely appropriate for every agent purchase. Define a matrix that connects transaction characteristics to application behavior.
Scenario | Possible acceptance posture | Delivery behavior |
|---|---|---|
low-value repeatable API call | scheme verification or early network state under policy | return result and retain reconciliation obligation |
costly asynchronous tool job | accepted payment state before expensive execution | queue job, expose status |
scarce digital entitlement | stronger confirmation requirement | reserve first, grant after threshold |
high-value or unusual destination | manual or elevated approval | do not sign or deliver automatically |
bridge-dependent operation | bridge-specific state machine | show bridge progress separately |
These are design patterns, not universal thresholds. The correct rule depends on the network, asset, facilitator, value, fraud model, product reversibility, and user experience.
Store both native and normalized states. Native state preserves what the network or facilitator actually said. The normalized state drives commerce workflow: waiting, accepted, delivered, remedy pending, or closed.
When a rule changes, version it. A transaction accepted under yesterday's threshold should remain explainable without applying today's policy retroactively.
Reconciliation Is A Continuous Worker, Not An Incident Tool
Callbacks improve responsiveness, but they cannot be the only source of payment state. Processes crash, messages duplicate, providers delay, and network observations evolve.
A reconciliation worker should continuously select transactions that are pending, unknown, accepted-but-undelivered, delivered-but-unclosed, or remedy-pending. For each item, it queries the authoritative systems and advances state idempotently.
A practical queue record includes:
The worker needs backoff, terminal-state rules, and escalation. Polling forever hides operational failure. Mark an item for investigation when it exceeds its expected window, when sources disagree, or when payment and delivery diverge.
Idempotency must span both ledgers. Reprocessing a confirmed event should not deliver twice. Reprocessing a delivery receipt should not overwrite a later refund. Every transition should compare the current version and preserve event history.
This worker is also where the platform can recover after downtime. It should be able to rebuild state from persisted references rather than depending on in-memory callbacks.
Refunds And Compensation Need A Reverse Path
Onchain payment systems often design the forward transfer carefully and leave refunds as a manual wallet operation. That makes support and accounting fragile.
Define the reverse path before launch:
Which delivery failures qualify for retry, credit, or refund?
Who authorizes the remedy?
Does the refund return the original asset to the original payer?
How are fees and partial fulfillment handled?
How is the refund linked to the original purchase?
What happens if the destination can no longer receive the asset?
Which state closes the merchant obligation?
Refunds are new onchain actions with their own wallet policy, transaction lifecycle, and confirmation rule. They do not erase the original transfer. The commerce ledger should show both value movements and the service outcome.
For very small payments, an account credit may be cheaper and faster than an immediate onchain refund, but that introduces a liability the merchant must track. The product should disclose the remedy and avoid silently substituting credit when a refund was promised.
Observe GOAT States Without Collapsing Their Meanings
GOAT Network offers a relevant environment for onchain agent payment workflows. AgentKit provides agent-facing wallet and action tooling; x402 supports HTTP-native payment interactions; ERC-8004 contributes identity and reputation context; the network provides EVM-compatible execution; and the broader architecture includes a BitVM2-based Bitcoin bridge and security design.
These capabilities produce different state domains:
AgentKit runtime state describes action validation and execution attempts.
x402 order or payment state describes the payment workflow.
GOAT transaction state describes execution-network observation.
BitVM2 bridge state describes relevant BTC bridge operations and challenges.
Bitcoin state describes Bitcoin confirmations and the applicable security boundary.
Do not compress them into “settled on Bitcoin.” Not every x402 payment traverses a BTC bridge, and Bitcoin does not directly execute every GOAT application transaction. A useful dashboard names the domain, source, timestamp, and confidence of each state.
GOAT's value in this context is not that the distinctions disappear. It is that developers can work across agent tooling, machine-readable payments, identity, programmable execution, and Bitcoin-secured infrastructure while retaining those distinctions.
A Launch Checklist For Onchain Agent Payments
Before enabling agent-triggered payment, verify the operational path:
Every x402 requirement maps to a versioned transaction intent.
Merchant identity and destination are checked before signing.
Wallet limits operate on typed transaction fields and cumulative exposure.
Broadcast, pending, included, reverted, replaced, and unknown are distinct states.
The acceptance matrix names network, scheme, asset, value band, and required evidence.
Payment acceptance and service delivery are stored separately.
Callbacks are backed by query-based reconciliation.
Duplicate requests cannot create duplicate payment or delivery silently.
Refund or credit flows reference the original purchase.
GOAT execution, x402, bridge, and Bitcoin states are not mislabeled as one finality event.
Then test the unhappy path. Lose the response after signing. Replace a pending transaction. Return a reverted transaction in a confirmed block. Deliver after acceptance and fail before recording the receipt. Receive the same callback twice. Restart reconciliation during a refund.
The system is ready when each case reaches a clear state without guessing whether value moved.
FAQ
What is onchain payment infrastructure for AI agents?
It is the wallet, payment protocol, identity context, network tracking, acceptance policy, reconciliation, and remedy infrastructure that lets an agent authorize and complete blockchain-based payments for services.
How does x402 connect HTTP requests to onchain payments?
The server returns machine-readable payment requirements with 402 Payment Required. The agent selects acceptable terms, authorizes payment through its wallet, and retries with payment evidence. The implementation then verifies and tracks the selected payment path.
Why is identity needed if the payment destination is onchain?
An address identifies a transaction endpoint, not the complete commercial counterparty. Identity can connect the service, controller, capabilities, and trust signals to the destination evaluated by policy.
When should an API deliver after an onchain payment?
The merchant should use a documented acceptance rule based on the payment scheme, network, asset, amount, product reversibility, and risk. There is no universal confirmation threshold for every API and transaction.
Is GOAT Network confirmation the same as Bitcoin finality?
No. GOAT execution confirmation, x402 payment state, BitVM2 bridge state, and Bitcoin finality are separate concepts. The relevant state depends on the actual transaction and bridge path.
Can AI agents make onchain payments without human confirmation?
They can execute transactions within preapproved policies, but limits should cover budgets, destinations, assets, networks, contract actions, and escalation thresholds. Higher-risk or unusual payments can still require human approval.
Settlement Is An Operating Process
Onchain payment does not end when a wallet broadcasts or a block includes a transaction. The merchant must translate network evidence into an acceptance decision, fulfill the service, reconcile uncertain states, and execute a remedy when value and delivery diverge.
Keep the commerce ledger and onchain ledger separate but correlated. Use x402 to express payment terms, identity to evaluate the counterparty, wallet policy to bound authority, network tracking to observe execution, and a reconciliation worker to close the loop.
GOAT Network brings those concerns into one developer context through AgentKit, x402, ERC-8004, programmable execution, and Bitcoin-secured infrastructure. The durable architecture comes from naming each state precisely and refusing to let one settled flag hide the operational work.
