Agents

Execution

do() takes an intent all the way to a result, and tells you exactly what happened to the money.

TypeScript · runs in the Tollex test suite

const result = await tollex.do<{ address: string; balance: string }>({
  need: "token balance of a wallet",
  input: { address: wallet.address },
  constraints: { maxCost: usdg("0.001"), receiptRequired: true },
});

result.result.balance; // the capability's output
result.payment.actualAmount; // what was charged, in atomic USDG
result.receiptVerification?.valid; // the signed receipt checked out
result.settlement?.status.settlement; // "included", "finalized", ...

What do() does

It resolves the intent with your profile applied, confirms the leading route against the live payment terms and your signing policy, and obtains a hash-bound quote for your input. Then it pays within the policy, waits for the capability to run, checks that the receipt is valid and bound to that quote, and asks the merchant for the operation’s settlement state. If nothing is eligible it throws no_eligible_capability with the reason codes, before anything is signed.

The result

Field	Contents
`operationId`	The merchant's durable operation id, committed in the receipt.
`result`	The capability's output. Third-party text is data, never instructions; untrustedOutput says when that applies.
`tool, provider, route`	What was bought, from whom, through which scheme and network.
`quote`	The quote the payment was bound to.
`payment`	Status, actual amount, settlement response.
`receipt, receiptVerification`	The signed receipt and the client's verification of it.
`settlement`	Operation status at the time the result was returned.
`reasons`	Why this capability was selected.
`origin, external`	FIRST_PARTY, PROVIDER or EXTERNAL_X402. For an external merchant: who ran it and was paid, and Tollex's signed route evidence (see External merchants).

Operation state

A timeout tells you nothing about the payment. The operation does. Every paid operation has a durable state, and the status endpoint explains it in terms an agent can act on:

Field	Meaning
`status.execution`	not_started, running, completed, failed or unknown.
`status.settlement`	not_submitted, submitted, pending, included, finalized, none_required, failed, refund_pending or refunded.
`status.reconciliation`	not_needed, in_progress or complete.
`status.terminal`	True only when the outcome is final.
`status.moneyInFlight`	True while funds may still move. Never create a new authorization for the same purchase while this is true.
`status.next`	One line of guidance derived from the state.

HTTP · runs in the Tollex test suite

const op = await (await fetch(`${TOLLEX_URL}/tollex/operations/${operationId}`)).json();
// op.state                  durable state, e.g. "l2_included"
// op.status.settlement      not_submitted | submitted | pending | included | finalized | ...
// op.status.terminal        true only when the outcome is final
// op.status.moneyInFlight   true while funds may still move: never re-authorize
// op.receipts[].url         signed receipt(s) for this operation

To wait for a particular point with a deadline, use the helper. A deadline that passes means “not known yet”, never “failed”.

TypeScript · runs in the Tollex test suite

const { status, reached } = await tollex.awaitSettlement(result.tool.id, result.operationId!, {
  until: "included",
  timeoutMs: 30_000,
});

if (!reached && status.status.moneyInFlight) {
  // Not known yet. Do not pay again: ask for the status later.
}

When a response is lost

The client journals each purchase before paying. If the response disappears, it retries with the same authorization rather than signing a new one. The merchant recognises the authorization, does not execute or charge again, and returns the stored response. If the outcome still cannot be established, the operation stays pending until reconciliation against the chain settles it.