testril CLI

testril mcp lets a coding agent use testril and pays for every paid call from your key. Each paid reply is testril's own answer, whose receipt states the charge and its currency, and the transaction when USDC left your wallet.

It serves MCP on stdio to the host (Claude Code, Codex, …) and relays every call to testril's MCP at --url. When testril answers with a price, the CLI pays on the network of the first row testril lists (testril lists the networks that can pay for the data first), or on --network: a voucher alone while your escrow balance covers the call, and also when the balance is unknown (every first call of a process), which is how usage credits serve an empty wallet with no USDC moving; otherwise the first row that fits --per-tx-budget-usd, an exact transfer or a deposit of USDC into testril's escrow of at least the row's minDeposit, then a voucher. One call moves USDC out of your wallet at most once. It never asks before paying; your budgets are the limit.

Install

npm installs it on macOS (Apple silicon and Intel) and Linux (x64 and arm64), with Node 18 or later. testril@latest makes npx check npm each time the host starts it, so a restart picks up a new release.

Claude Code:

claude mcp add testril --env TESTRIL_PAYER_KEY=<hex private key> -- \
  npx -y testril@latest mcp --per-tx-budget-usd 0.10 --weekly-budget-usd 1

Codex: the same arguments to codex mcp add.

Grok Build: add to ~/.grok/config.toml, with TESTRIL_PAYER_KEY set in your shell:

[mcp_servers.testril]
command = "npx"
args = ["-y", "testril@latest", "mcp", "--per-tx-budget-usd", "0.10", "--weekly-budget-usd", "1"]
env = { TESTRIL_PAYER_KEY = "${TESTRIL_PAYER_KEY}" }

To run a checkout instead, cargo build --release -p testril-cli and use "$PWD/target/release/testril" mcp … in place of npx -y testril@latest mcp ….

Flags

| Flag | Required | Limits | |---|---|---| | --per-tx-budget-usd <dollars> | yes | one deposit or exact transfer | | --daily-budget-usd <dollars> | no | all deposits and exact transfers this key signed in the last 24 hours | | --weekly-budget-usd <dollars> | no | … in the last 7 days | | --monthly-budget-usd <dollars> | no | … in the last 30 days | | --url <url> | no | testril's MCP; default https://api.testril.si/mcp | | --network eip155:<chain-id> | no | the network every payment uses, in place of the first row's; testril refuses a network that cannot pay for the data |

Amounts are exact dollars of USDC, up to 6 decimals (0.10). A deposit or transfer must fit every budget you set.

The payment log

Each deposit and exact transfer the CLI signs is appended to ~/.testril/payments/<payer address>.jsonl, with its scheme. Vouchers move no money and are not logged. The periodic budgets read the log, so a restart or a second session on the same key counts earlier payments. Payments on every network count against the same budgets. Another machine does not share the log.

Withdraw a deposit

The unspent part of a deposit stays in testril's escrow, the x402BatchSettlement contract at 0x4020074e9dF2ce1deE5A9C1b5c3f541D02a10003 on every chain. Only your key can take it back, in two transactions the channel's withdrawDelay seconds apart; the key needs ETH for gas.

1. Ask your agent for inspect { subject: "channels", payer: "<your address>", network: "<network>" }. Each channel states its channelConfig, its balance and its chargedCumulativeAmount. You can withdraw balance − chargedCumulativeAmount: testril claims the rest.
2. Start the withdrawal, with the channelConfig fields in this order: payer, payerAuthorizer, receiver, receiverAuthorizer, token, withdrawDelay, salt.

ESCROW=0x4020074e9dF2ce1deE5A9C1b5c3f541D02a10003
CONFIG='(<payer>,<payerAuthorizer>,<receiver>,<receiverAuthorizer>,<token>,<withdrawDelay>,<salt>)'
cast send "$ESCROW" 'initiateWithdraw((address,address,address,address,address,uint40,bytes32),uint128)' \
  "$CONFIG" <atoms> --private-key "$TESTRIL_PAYER_KEY" --rpc-url <rpc url>

3. After withdrawDelay seconds, finish it. The USDC goes back to your address.

cast send "$ESCROW" 'finalizeWithdraw((address,address,address,address,address,uint40,bytes32))' \
  "$CONFIG" --private-key "$TESTRIL_PAYER_KEY" --rpc-url <rpc url>

When it does not pay

The call ends in a refusal like any other tool's: outcome: "error", a kind that says why, a message, and a remedy with the next step (not an MCP isError; that is only a payment required):

| kind | Meaning | |---|---| | payment_over_budget | the deposit or transfer would pass a budget; nothing was signed | | payment_state_unsigned | testril reported this channel's spend without your key's signature | | payment_refused | testril refused the payment (code says how), or the payment log could not be used | | payment_cancelled | the host cancelled the call before another payment was signed |