Getting started

Experimental. Named API credit provider integrations are not available.

An agent needs to pay for an API call, but its user holds a balance with an API credit provider rather than tokens in the agent's wallet. The API credit provider integration connects that balance to a payment the API can verify.

For example, a platform could give a customer a prepaid budget for research APIs. The customer authorizes an agent to spend part of that budget. A participating API receives the agreed token payment; it does not need to keep an account in the platform's credit system.

Who does what?

Credits are the provider's accounting balance. They are not a new settlement currency that every merchant must adopt. The integration must turn authorized credits into an actual token payment.

Follow a payment

1. The merchant quotes a price. An HTTP payment challenge describes the amount, token, recipient, and supported payment flow.
2. The customer authorizes spending. The provider approves a bounded amount for the intended payment.
3. The provider funds the channel. Its program reduces the available credits and supplies backing tokens as part of the funding transaction.
4. The merchant gets paid. Channel distribution pays the merchant. For a one-shot charge, the verifier checks the merchant's actual token credit before returning a payment receipt.
5. Unused funds return to credit. When a session ends with unspent principal, the provider recovers the returned tokens before restoring the corresponding credits.

Funding and refund callbacks execute inside the channel transaction. If a required callback fails, the transaction's state changes and token transfers roll back. Transaction fees can still be charged.

One call or an ongoing session

• Charge: pay a fixed amount for one request. The channel-backed flow opens, settles, and distributes in one transaction. The full quoted amount is spent; the refund callback still runs with zero returned principal.
• Session: authorize a budget for multiple deliveries. The channel can receive top-ups, pay for usage, and return unused principal when it closes.

As an accounting example, start with 100 credits backed one-for-one by token units. Funding a session with 60 leaves 40 available credits. If the session spends 45 and returns 15 to the provider's custody, the customer ends with 55 credits and the merchant receives 45 token units.

What can I use today?

The latest payment-channel runtime supports ordinary channels and optional hooked channels at the same program address. This revision has not been deployed. Pay and pay-kit have not been updated to emit its new hooked instructions, so their existing experimental configuration is not a ready-to-use integration with this runtime. Direct-transfer charges are unchanged; this revision does not add API credit provider support to x402.

The local Rust example demonstrates token-backed credits using the on-chain SDK. Its Surfpool end-to-end test passes locally. Selecting an unavailable named provider is rejected rather than advertised to customers.

What happens to existing channels?

Existing channels keep working as before. Adding support for provider callbacks does not change their payment terms or require customers to move their funds.

A customer opts into provider funding when opening a new channel with hooks. Those hooks are fixed for that channel's lifetime; they cannot be attached to an existing channel.

The compatibility test verifies that existing clients can continue using and opening standard channels after the program upgrade.

Choose your role

• Providing credits: build the provider program, test backing and refund safety, and submit an integration for review.
• Accepting credits: understand the merchant setup in Pay or pay-kit and what must be supported before enabling a provider.