Scheme identifier: @faremeter/flex
Per-request on-chain payment schemes have two fundamental limitations for agentic workflows:
-
Variable costs require upfront knowledge. The client must know the exact payment amount before making a request. This works for fixed-price resources, but breaks down when the cost depends on request content (e.g., token count for AI inference), response content (e.g., data transfer size), or metered usage over time (e.g., streaming, long-running operations). The service either overcharges (bad for users) or undercharges (bad for operators).
-
On-chain confirmation adds latency to every request. Each request requires a separate on-chain transaction that must be confirmed before the service can be delivered. For high-frequency, low-value interactions -- the common case in agentic workflows -- this per-request overhead dominates the total response time.
The flex scheme introduces prepaid escrow accounts that clients fund in advance. Instead of paying per-request, the middleware debits from a pre-existing balance based on actual usage. Settlement happens asynchronously -- the facilitator can grant access optimistically and batch authorizations for on-chain submission later, decoupling service delivery from on-chain confirmation.
- Client: The party making requests and paying for resources.
- Middleware: Generates payment requirements, gates access to the resource, and receives payment.
- Facilitator: Validates payments and settles them on-chain. Acts as the co-signer for escrow account transfers.
The middleware and facilitator may be the same service or separate services that communicate via API.
-
Discovery: The client requests a resource and receives payment requirements from the middleware. The requirements include the facilitator's public key.
-
Account Creation: The client creates an escrow account on-chain governed by a contract that requires dual authorization. The account is configured with both the client's key and the facilitator's public key as co-signers. Transfers out of the account need signatures from both parties.
-
Funding: The client deposits tokens into the escrow account via their wallet. A single escrow account can hold multiple token types (mints).
-
Session Key Registration: The client registers a session key with the escrow account via an on-chain transaction. The session key is a separate keypair generated by the client specifically for signing payment authorizations. This works with any account type, including smart wallets and multisigs that cannot sign arbitrary off-chain messages.
-
Usage and Holds: When making requests, the client and middleware negotiate a hold before work begins:
a. Hold Request: The middleware responds to the client's initial request with a hold amount representing the estimated or maximum cost for the operation.
b. Client Authorization: The client signs an authorization for the hold amount using their session key. The client may authorize a higher ceiling than requested to allow for variable costs without additional round-trips.
c. Hold Validation: The middleware forwards the signed hold authorization to the facilitator. The facilitator validates the authorization (verifying the signature and confirming sufficient escrow balance) and returns success. If validation fails, the middleware returns an error to the client.
d. Service Delivery: With a valid hold in place, the middleware performs the requested work.
e. Additional Authorization: If the middleware requires more than the initially authorized amount during service delivery, it may request additional authorization from the client. The client can approve, partially approve, or decline.
f. Settlement Request: After completing the work, the middleware reports the actual amount consumed to the facilitator. The hold converts to a pending settlement for the actual amount used.
-
Authorization Submission: The facilitator collects the client's signed authorizations and can batch multiple authorizations before submitting them on-chain. This allows for faster and optimistic settlement strategies where the middleware grants access before on-chain confirmation. When submitted, each authorization creates a pending settlement with a configurable refund timeout. The authorization specifies the token mint, amount, and a split distribution describing how funds are divided among recipients at finalization.
-
Refund Window: During the refund timeout period, the facilitator can reduce or cancel the pending settlement (e.g., if the merchant did not deliver the service). The middleware authorizes refunds off-chain; the facilitator submits them on-chain.
-
Finalization: After the refund timeout expires, the pending settlement is finalized. This transfers funds from the escrow account to the merchant and closes the pending settlement record.
-
Escrow Closure: When the client wants to close the escrow account and withdraw remaining funds, they request closure from the facilitator. The facilitator co-signs the closure only after all pending settlements have been finalized. If the facilitator becomes unresponsive, the client can unilaterally close the escrow account after the deadman timeout expires.
Note: Overspend policy configuration is TBD. The initial implementation may reject requests when the escrow account balance is insufficient. Future versions may support configurable policies such as limited credit or operator-assumed risk.
Session keys enable clients to authorize payments without needing the escrow account's private key for each authorization. This is essential for smart wallets and multisigs that cannot sign arbitrary off-chain messages.
-
Registration: The client registers a session key with the escrow account via an on-chain transaction.
-
Authorization: The client signs payment authorizations using the session key. Each authorization specifies the token mint, split distribution, amount, and a unique authorization_id. Replay protection is enforced on-chain through PDA uniqueness -- each pending settlement PDA includes the authorization_id in its seeds, so duplicate submissions fail at account initialization.
-
Revocation: The client can revoke a session key at any time. A grace period allows the facilitator to settle any outstanding authorizations before the key becomes fully invalid.
Authorizations support split payments, where funds are distributed to multiple recipients at finalization. Instead of specifying a single recipient, each authorization includes a splits vector: a list of (recipient, basis points) pairs that must sum to 10000 (100%).
A single-recipient payment is simply a split with one entry at 10000 bps. Multi-recipient splits enable use cases like platform fees, referral commissions, royalty distributions, and facilitator fees without requiring multiple separate transactions.
Splits are part of the client-signed authorization message. The facilitator cannot alter the distribution -- clients must explicitly agree to every recipient and proportion. At finalization, the on-chain program distributes tokens proportionally according to the signed splits.
| Aspect | Per-Request Payment | Flex Scheme |
|---|---|---|
| Payment timing | Per-request, upfront | Post-request, from prepaid balance |
| Amount knowledge | Must know before request | Determined after request |
| On-chain transactions | One per request | Batched settlements |
| Service latency | Blocked on chain confirmation | Optimistic, settles asynchronously |
| Client complexity | Build and sign transactions | Fund account once, authenticate requests |
| Use cases | Fixed-price APIs | Metered usage, streaming, variable pricing |
The flex scheme is designed as a settlement layer, not tied to any single payment protocol. It can serve as the backend for:
- x402 -- HTTP-native payment negotiation
- MPP (Machine Payment Protocol) -- agent-to-agent payment coordination
- Any protocol that can express a hold-and-settle flow with signed authorizations
The flex scheme supports refunds through an on-chain refund window. When the facilitator submits an authorization, it enters a pending state for a configurable timeout period. During this window:
- The facilitator can reduce or cancel the pending amount (e.g., if the merchant did not deliver the service)
- The middleware authorizes refunds off-chain; the facilitator submits them on-chain
Once the refund window closes, the settlement is finalized and funds transfer to the merchant. This is enforced on-chain, not through off-chain facilitator logic. The refund window balances the merchant's need to eventually receive payment with the client's need for recourse if something goes wrong.
The facilitator pays on-chain transaction fees when batching settlements. This cost is amortized across multiple payments in each batch, making it economical for high-frequency, low-value transactions.
The flex scheme is designed to work on any chain that supports:
- Multi-signature or shared-authority token accounts
- Payment channel primitives (or equivalent escrow mechanisms)
The initial implementation targets Solana, with EVM support planned.
Each escrow account has a single facilitator. The client creates a separate escrow account for each facilitator they work with.
- Dual authorization: The on-chain contract requires signatures from both the client (via session key) and facilitator for any transfer out of the escrow account. Neither party can unilaterally move funds (except via deadman switch).
- Client-initiated transfers: The client signs authorizations specifying the token mint, amount, and split distribution (recipients and proportions). The facilitator can only submit authorizations the client has signed.
- Balance verification: The facilitator verifies on-chain balances before accepting authorizations.
- Replay protection: Each authorization includes a unique authorization_id. Replay protection is enforced through PDA uniqueness -- each pending settlement PDA includes the authorization_id in its seeds, so the
initconstraint rejects duplicate submissions. Expiry-based validation provides a second layer: authorizations expire before finalization completes, preventing replay after the pending settlement PDA is closed. - Refund window: Pending settlements cannot be finalized until the refund timeout expires, giving time to cancel erroneous or disputed charges.
- Escrow closure gating: The escrow account cannot be closed while pending settlements exist. The facilitator must finalize all pending settlements before co-signing escrow closure.
- Deadman's switch: If the facilitator becomes unresponsive (no activity within a configurable timeout), the client can unilaterally close the escrow account and recover all funds. Any pending settlements the facilitator failed to finalize are voided.