Settlement Rails

Every rail plugs in behind one adapter, outside the kernel

The kernel speaks to a rail through the PaymentAdapter trait: authorize before the tool runs, capture or release after it, and refund for a later reversal.

authorize reserves up to the quoted amount on the rail. After the call, metering produces the observed cost: a held authorization captures it, or releases cleanly when it is zero. The grant and the hold admit the call. A payment on the rail never authorizes one by itself, and a MustPrepay mandate with no adapter configured is refused before dispatch.

Each rail reports its own RailSettlementStatus: Authorized, Captured, Settled, Pending, Failed, Released, or Refunded. These fold into the four values of the receipt's SettlementStatus, which records whether money is moving, has moved, or has stopped; the rail keeps intermediate detail in its metadata.

Read more in Budgets and metering, which covers the hold the kernel records before dispatch.

Each adapter declares whether a charge is held or prepaid

The operator selects one adapter at kernel-host configuration with CHIO_PAYMENT_ADAPTER=sim|http-x402|http-acp. Simulation is the default, an unrecognized value is rejected as a configuration error, and the two HTTP adapters delegate money movement to a facilitator at CHIO_PAYMENT_BASE_URL.

The kernel checks that the state authorize returns, Held or PrepaidFinal, matches the adapter's declared rail mode, and a refused authorization stops the paid path. For a metered call quoted at 100 units and observed at 85, ACP authorizes the 100-unit ceiling, then captures 85 through its terminal endpoint and validates each response against the operation it bound. Budget reconciliation restores 15 units of capacity, a fact separate from the payment result.

x402 completes final prepayment at authorization, so the kernel skips a second capture, and a lower measured cost triggers no remote refund by itself. An x402 result is not settled by default: a facilitator response that omits the field reads as unsettled, and the adapter refuses to complete the prepayment on it. Both HTTP modes take a facilitator base_url and an optional bearer token; the operator supplies the facilitator service, its custody, and the payment account. A PaymentResult carries transaction_id, settlement_status, and metadata, and a pending result is a recorded state short of final payment.

Read more in x402 payments, and in the 100, 85, 15 walkthrough for the exact authorization request and terminal result.

The intent sets the payment posture before the call runs

A metered call carries one MeteredSettlementMode, chosen on the capability or the governed intent and recorded on the receipt.

/// Policy-visible settlement posture for quoted metered billing.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MeteredSettlementMode {
    /// The action should not execute unless the quoted amount is prepaid.
    MustPrepay,
    /// The action may execute against a hold and settle later via capture/release.
    HoldCapture,
    /// The action may execute first and settle later with truthful pending state.
    AllowThenSettle,
}

1. Must prepay. must_prepay captures the quoted amount before execution. Prepaid-final skips capture, and a lower observed cost refunds nothing automatically. When final prepayment cannot be confirmed, or no adapter is configured, the kernel refuses the call before execution and it never runs unpaid.
2. Hold and capture. hold_capture authorizes the quote as a hold, captures a positive actual cost at or below that ceiling, and releases a zero-cost hold. The original authorization and its terminal outcome resolve under the provider's contract.
3. Allow then settle. allow_then_settle permits deferred settlement, and configured admission can still reserve budget and authorize payment. The host arranges and reconciles the deferred payment, keeping pending and failed outcomes distinct from final settlement.

A public agent with no track record fits must_prepay. A known high-volume partner can run on hold_capture, and an internal team rail through a ledger can use allow_then_settle, because the counterparty is your own treasury. The rail kind and the settlement mode are separate fields, so choose an adapter and admission path that support the mode.

Read more in Tool pricing, which computes the quoted cost before the rail sees the authorization.

A governed payment carries the intent and approval that allowed it

Chio initiates outbound payments as well as recording inbound ones. A bound governed intent, with approval evidence when policy requires it, drives the same adapter through authorize before the tool runs and capture or release after.

Before dispatch, the kernel derives a GovernedPaymentContext from the intent's binding hash and the approval token's id, or the threshold proposal standing in for it, and hands it to authorize beside an optional CommercePaymentContext. After execution it stamps payment_reference and settlement_status into the receipt's FinancialReceiptMetadata, so the settlement binds back to the authority that allowed it.

let governed = request
    .governed_intent
    .as_ref()
    .map(|intent| {
        intent
            .binding_hash()
            .map(|intent_hash| GovernedPaymentContext {
                intent_id: intent.id.clone(),
                intent_hash,
                purpose: intent.purpose.clone(),
                server_id: intent.server_id.clone(),
                tool_name: intent.tool_name.clone(),
                approval_token_id: request
                    .approval_token
                    .as_ref()
                    .map(|token| token.id.clone())
                    .or_else(|| {
                        request
                            .threshold_approval_proposal
                            .as_ref()
                            .map(|proposal| proposal.body.proposal_id.clone())
                    }),
            })
            .map_err(|error| {
                PaymentError::RailError(format!(
                    "failed to hash governed intent for payment authorization: {error}"
                ))
            })
    })
    .transpose()?;

Two shapes carry the authorization. The HTTP shape posts to a facilitator's /authorize endpoint, for an x402 per-request stablecoin payment or an ACP shared payment token. The EIP-3009 shape calls prepare_transfer_with_authorization, which computes the EIP-712 transferWithAuthorization digest and returns a PreparedTransferWithAuthorization. An ApprovalBinding derives that digest's chain, payee, amount, and token from a verified GovernedApprovalToken, which folds them into one governed_intent_hash, and Eip3009NonceStore keeps each nonce single-use.

No step in this path holds funds. Chio computes and authorizes, a wallet signs, and an external facilitator broadcasts; the EIP-3009 lane returns a digest and leaves signing and submission to the external executor. For these off-chain rails the configuration offers simulation or facilitator delegation, with no operator-managed custody or broadcast mode.

Read more in Authoritative Spend for the authority and outcome evidence a payment requires, and in Verify Commerce Evidence, whose fixture checks recorded projections.

Whichever rail moves the money, the receipt records the same fields

The host observes provider notifications and appends outcome evidence beside the receipt, which keeps the fields it was signed with.

• payment_reference: the rail's stable identifier, such as a card charge id, an ACH trace number, or a transaction hash, for downstream reconciliation.
• settlement_status: NotApplicable, Pending, Settled, or Failed.
• metered_billing: the quoted units, the observed units, and the MeteredSettlementMode.

A CapitalExecutionRail instruction is a separate execution record linked to the receipt; tool-call receipts do not carry it as a field. Rail settlement outcomes are observed and recorded, while the holds and caps on the grant prevent spend before dispatch.

A company can authorize an agent to buy work without giving the provider control of its budget, and the provider can retain the receivable, sell it to a factor, or agree to channel settlement. Four records answer the four questions about one paid call:

1. May this call incur a charge? The capability, admission, budget hold, and execution nonce, in Authoritative Spend.
2. Who is owed? An immutable obligation and its current authenticated creditor, in Obligations.
3. How will value move? The selected adapter or contract execution; payment channels and clearing are alternative arrangements.
4. Can the books close? The original rail result, its financial linkage, and any required finality evidence, in Reconciliation.

Next: verify one payment lifecycle

Run one authorized call through the selected adapter and retain its authorization id, terminal result, and reconciled receipt.