> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chance.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools

> Every tool on the hosted MCP server: parameters, annotations, cost and what each returns.

The hosted server is at `https://harness.chance.cc/api/mcp`. It speaks Streamable HTTP over `POST` only, keeps no session, and answers with JSON. The local stdio package forwards every message to this server, so the tools below are the same in both. Setup: [Local MCP](/mcp-local) and [Connectors](/connectors).

**Credentials.** An API key (`x-api-key` or `Authorization: Bearer`) reaches every tool. An OAuth token reaches what its scope allows: `mcp` covers the verification and account tools and `strk20_relay_status`; `wallet` adds every other tool. Without the `wallet` scope, a wallet tool returns an error asking you to reconnect and approve wallet access. A request with no valid credential gets `401` with a `WWW-Authenticate` header pointing at `/.well-known/oauth-protected-resource`.

**Availability.** The wallet, proposal, status and STRK20 tools exist only when the deployment has escrow wallets configured. `check_connection` reports `escrowTools: true` when this credential can use them.

**Results.** Each tool returns text. Most end with a fenced JSON block holding the same data. A failure is a result with `isError: true`, not a protocol error. A wallet parameter accepts the wallet's id or its name.

## Verification

### verify\_intent

Checks an action against an intent and returns a verdict with its receipt. One credit, refunded if the run fails. Annotations: `readOnlyHint: false`, `destructiveHint: false`.

| Parameter | Type | |
| - | - | - |
| `intent` | string | Required. The rules. |
| `action` | string or object | Required. The action, or the exact payload. |
| `context` | object | Optional. Facts for the judge. `reference: {source, excerpt}` carries third-party documentation. |
| `venue` | enum | Optional. `hyperliquid`, `limitless`, `polymarket`, `dimes`, `myriad`, `orderly`, `derive`, `lifi`, `meow`, `liquid`, `robinhood`, `x402`, `agentcards`, `uniswap`, `solana`, `starknet`, `alchemy`, or `evm` (alias for `alchemy`). |

Returns the verdict, reasoning, a proof summary, the verification id and the balance, then JSON: `id`, `requestHash`, `status`, `verdict`, `reasoning`, `mode`, `venue`, `actionFamily`, `proof`, `creditsRemaining`. Field details: [Verification request](/api-reference/verification-request).

### get\_verification

Fetches a past verification by `id` (UUID or `requestHash`). Free. Annotations: `readOnlyHint: true`.

Returns `id`, `requestHash`, `status`, `verdict`, `reasoning`, `createdAt` and `proof` with `anchorStatus`, `transcriptUri` and `explorerTx`.

## Account

### check\_connection

Confirms the credential works, without spending a credit. No parameters. Free. Annotations: `readOnlyHint: true`, `idempotentHint: true`.

Returns `ok`, `account` (email, else wallet address, else account id), `creditsRemaining`, `escrowTools` and `authMethod` (`api_key` or `oauth`).

### topup\_credits

Buys credits with USDC on Base over x402. Costs no credits. Annotations: `readOnlyHint: false`, `destructiveHint: false`.

| Parameter | Type | |
| - | - | - |
| `credits` | integer | Required. 20 to 10,000. |

Called without a payment, it returns `isError: true` with the x402 terms (in the text, in `structuredContent` and in `_meta["x402/payment-required"]`), the HTTP endpoint and the guide URL. Called again with a signed x402 v2 `PaymentPayload` in `_meta["x402/payment"]`, it settles the payment, credits this account and returns the settlement in `_meta["x402/payment-response"]`. See [Credits](/concepts/credits#top-up-over-mcp).

## Wallets

These tools need the `wallet` scope and are free.

### create\_escrow\_wallet

Annotations: `readOnlyHint: false`, `destructiveHint: false`.

| Parameter | Type | |
| - | - | - |
| `name` | string | Required. Unique on the account. |
| `chain` | `base` \| `solana` \| `starknet` | Required. Permanent. |
| `mode` | `autonomous` \| `safe` | Required. Permanent. Safe mode supports Base and Starknet. |
| `mandate` | string | Required. The rules the judge checks each proposal against. |
| `limits` | object | Optional. `maxPerTxUsd`, `dailyCapUsd` (rolling 24 hours), `tokenAllowlist` (token contract addresses; a well-known symbol resolves to its one real address on the chain, any other symbol permits nothing), `recipientAllowlist`. |

Returns the address to fund, what the wallet needs for gas on its chain, and JSON: `id`, `name`, `chain`, `mode`, `address`, `mandate`, `limits`.

### update\_escrow\_wallet

Changes a wallet's name, mandate or limits. Mode and chain cannot change. Annotations: `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: true`.

| Parameter | Type | |
| - | - | - |
| `wallet` | string | Required. |
| `name` | string | Optional. |
| `mandate` | string | Optional. |
| `limits` | object | Optional. Same fields as on create. Sent to the custodian as well as saved. |

At least one of `name`, `mandate` or `limits` is required. A change that loosens the rules is applied, not refused, and the reply says what it loosened. Returns JSON: `wallet`, `name`, `mode`, `mandate`, `limits`.

### list\_escrow\_wallets

No parameters. Archived wallets are left out. Annotations: `readOnlyHint: true`.

Returns one entry per wallet: `id`, `name`, `chain`, `mode`, `address`, `mandate`, `balanceUsd`, `tokenCount`, `provider`, `custody`, `rules` and `explorerAddressUrl`. `rules.limits` holds only the limits that are set. `rules.enforcement` says, per limit, who refuses a violation: `signer` (the custodian), `chance` (Chance's check before signing) or `judge` (only the judge weighs it).

### get\_escrow\_balances

| Parameter | Type | |
| - | - | - |
| `wallet` | string | Required. |

Annotations: `readOnlyHint: true`. Returns `walletId`, `name`, `address`, `balanceUsd` and `balances`. Each balance has `amount` in base units and `amountFormatted` in whole units; the proposal tools take whole units.

### list\_swap\_tokens

| Parameter | Type | |
| - | - | - |
| `chain` | `ethereum` \| `base` | Required. |

Annotations: `readOnlyHint: true`, `idempotentHint: true`. Returns ETH (address `native`) and the token contracts Chance has verified on that chain, each with `symbol`, `name`, `address`, `decimals` and `logoUrl`.

### quote\_escrow\_swap

Prices a swap without proposing it. Nothing is simulated, judged, signed or recorded, and the quote is not held. Annotations: `readOnlyHint: true`.

Takes the same parameters as `escrow_swap` except `note`. Returns `walletId`, `name`, `chain`, `slippageBps` and `swap` (amounts in, out and minimum, price impact, estimated gas, and whether an approval is needed).

## Proposals

These tools need the `wallet` scope. Each one simulates the action, checks the wallet's limits, and runs the judge against the wallet's mandate. One credit when the judge runs; a proposal the limits block first is free. Annotations: `readOnlyHint: false`, `destructiveHint: true`.

Each returns the verdict, the reasoning, a one-line simulation summary, and then one of: the explorer link (executed), an approval link to send to the owner (held, with its expiry), or "not executed". Then a proof summary, the transaction id, the balance, and JSON with the full proposal result: `txId`, `status`, `verdict`, `reasoning`, `requestHash`, `simulation`, `approvalUrl`, `txHash`, `scanId`, `creditsRemaining`, `proof`. An approval link means the funds have not moved. Field details: [Escrow wallets API](/api-reference/escrow-wallets#result).

`note` on every proposal tool is context for the judge. It is treated as untrusted narration that cannot grant permission, and it is cut at 2,000 characters.

A call that times out on the client still creates the proposal on the server. Find it with `list_escrow_transactions`.

### escrow\_transfer

Sends a named asset as-is. On Solana it always waits for the owner.

| Parameter | Type | |
| - | - | - |
| `wallet` | string | Required. |
| `asset` | string | Required. Symbol, for example `USDC`. On Starknet: STRK, ETH, USDC or USDT. |
| `amount` | string | Required. Whole units, for example `"500"`. |
| `to` | string | Required. Recipient address. |
| `chain` | `ethereum` \| `base` \| `solana` \| `starknet` | Required. Must be the wallet's chain. |
| `note` | string | Optional. |

### escrow\_swap

Quotes on the Uniswap Trading API, builds the batch (an approval for exactly the sell amount when needed, then the swap) and proposes it. Base and Ethereum wallets only. The JSON also carries `swap`.

| Parameter | Type | |
| - | - | - |
| `wallet` | string | Required. |
| `sell` | string | Required. A 0x address, `ETH`, `WETH`, `USDC`, or a symbol the wallet holds. |
| `buy` | string | Required. A 0x address, `ETH`, `WETH` or `USDC`. |
| `amount` | string | Required. Amount to sell, in the sell token's units. |
| `chain` | `ethereum` \| `base` | Required. Must be the wallet's chain. |
| `slippageBps` | integer | Optional. 1 to 1,000, default 50. Sets the minimum output in the signed swap. |
| `note` | string | Optional. |

### escrow\_execute

Proposes a raw transaction. Send exactly one of `transaction`, `calls`, `solanaTransaction` or `starknetCalls`.

| Parameter | Type | |
| - | - | - |
| `wallet` | string | Required. |
| `chain` | `ethereum` \| `base` \| `solana` \| `starknet` | Required. Must be the wallet's chain. |
| `transaction` | object | One EVM transaction, `{to, value, data}`. |
| `calls` | object\[] | An EVM batch of `{to, value, data}`. |
| `solanaTransaction` | string | A base64 Solana transaction. |
| `starknetCalls` | object\[] | A Starknet multicall of `{contractAddress, entrypoint, calldata}`, executed as one transaction. |
| `starknetProof` | object | Optional. `{facts, data}`, required only for a call to the privacy pool's `apply_actions`. Not stored. |
| `note` | string | Optional. |

### escrow\_pay\_x402

Pays for an HTTP resource that charges with x402, and returns what the resource sends back. Chance requests the URL itself, reads the terms from the 402 response, and puts the exact amount, token and recipient through the gate. EVM wallets only. A self-custodial safe wallet cannot pay this way.

| Parameter | Type | |
| - | - | - |
| `wallet` | string | Required. |
| `url` | string | Required. The final URL. Redirects and private or loopback hosts are refused. The resource must answer 402 with x402 v2 terms in its JSON body. |
| `method` | `GET` \| `POST` | Optional. Default `GET`. |
| `maxAmount` | string | Optional. Refuse if the invoice is above this, in whole tokens. |
| `note` | string | Optional. |

When the payment executes, the reply includes up to 8,000 characters of the resource's response.

## Status

These tools need the `wallet` scope, are free, and are read-only.

### list\_escrow\_transactions

| Parameter | Type | |
| - | - | - |
| `wallet` | string | Optional. One wallet only. |
| `status` | enum | Optional. `verifying`, `awaiting_user`, `executing`, `executed`, `failed`, `blocked` or `expired`. |
| `limit` | integer | Optional. 1 to 50, default 20. |

Newest first. Each entry: `id`, `walletId`, `status`, `verdict`, `summary`, `explorerUrl`, `approvalUrl` (while awaiting the owner), `error`, `createdAt`.

### get\_escrow\_transaction

| Parameter | Type | |
| - | - | - |
| `id` | string | Required. The `txId` from a proposal. |

Returns `id`, `walletId`, `status`, `verdict`, `txHash`, `explorerUrl`, `approvalUrl` (while awaiting the owner), `error`, `createdAt`, `updatedAt`. An approval past its window reads `expired`.

## STRK20 private actions

Starknet wallets only. All free.

<Warning>
  `strk20_sign_proof_invocation` followed by `strk20_relay_private_action` puts a private action on chain without a proposal: no simulation, no limit check and no verdict. The gated route is `escrow_execute` with `starknetCalls` and `starknetProof`. Until the sign-and-relay path is gated, treat it as ungated.
</Warning>

### strk20\_relay\_status

Whether private actions can be relayed through AVNU's paymaster: key configured, relay reachable, key accepted. No parameters. Does not need the `wallet` scope. Annotations: `readOnlyHint: true`.

### strk20\_pool\_fee

What the relayer charges, as a withdraw action to add to the action set before proving. Annotations: `readOnlyHint: true`.

| Parameter | Type | |
| - | - | - |
| `feeToken` | string | Optional. Token address. Default STRK. |

### strk20\_sign\_proof\_invocation

Signs a private action with the wallet's key and proves it. The signature authorizes the action. Annotations: `readOnlyHint: false`, `destructiveHint: true`.

| Parameter | Type | |
| - | - | - |
| `wallet` | string | Required. A Starknet wallet. |
| `compileActionsCalldata` | string\[] | Required. Felts for `compile_actions(user_addr, user_private_key, client_actions)`. The first must be the wallet's address. |

Returns `wallet`, `address`, `pool`, `calldata`, `signature` and `proof`. The proof expires in about five minutes.

### strk20\_viewing\_key\_signature

Signs the fixed viewing-key derivation message for the wallet. The client derives the viewing key from it, which decrypts the wallet's shielded notes. No caller-supplied bytes are signed. Annotations: `readOnlyHint: false`, `destructiveHint: false`.

| Parameter | Type | |
| - | - | - |
| `wallet` | string | Required. A Starknet wallet. |

Returns `wallet`, `address`, `signature`.

### strk20\_relay\_private\_action

Relays a proven `apply_actions` call through the paymaster. The wallet pays no STRK for gas. Annotations: `readOnlyHint: false`, `destructiveHint: true`.

| Parameter | Type | |
| - | - | - |
| `call` | object | Required. `{contractAddress, entrypoint, calldata}` from the prover. |
| `proof` | string | Required. Base64 proof. |
| `proofFacts` | string\[] | Required. Hex felts. |
| `feeToken` | string | Optional. Must match the token the fee was quoted in. |

Returns `txHash` and `trackingId`.