> ## 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.

# Starknet wallets and private balances

> How Starknet escrow wallets deploy and pay fees, what the Private balance shows, and how private STRK20 actions run over MCP.

## Wallets

A Starknet escrow wallet is a Ready v0.5.0 account contract on Starknet mainnet. Its address is known at creation, before the contract exists on chain, so you can fund it right away.

| | Autonomous | Safe |
| - | - | - |
| Key | Chance signs for the wallet after an `ALLOW`, or after you confirm a held proposal. | A Starknet key that only you control. Chance cannot sign for it. |
| Deployment | The account deploys itself on its first transaction and pays a one-off deployment fee in STRK. | The account is activated on your first confirm. That confirm asks for two signatures in the browser: one to activate the account, one for the transaction. Activation is paid in STRK from the wallet. Later confirms need one signature. |
| Confirms | Held proposals are confirmed at the approval link. | Every proposal is confirmed and signed by you in the browser. |

* Fees are paid in STRK. Keep STRK in the wallet in addition to what it will spend.
* `escrow_execute` with `starknetCalls` runs the calls as one multicall through the account's `__execute__`. It succeeds or fails as a whole.
* `escrow_transfer` supports `STRK`, `ETH`, `USDC` and `USDT`. For other tokens, propose the token's `transfer` call with `escrow_execute`.
* Swaps, x402 payments and dashboard withdrawals are not available on Starknet.
* Explorer links for escrow transactions point to [voyager.online](https://voyager.online).

See [Escrow wallets](/escrow) for the proposal lifecycle and [Wallet limits](/wallet-limits) for the limits.

## Private balances

STRK20 is Starknet's privacy pool. A supported token can have a shielded balance in the pool beside its ordinary public balance.

The wallet page in the dashboard shows a **Private** section for Starknet wallets: the shielded balance, found by scanning the pool with the wallet's viewing key.

* A private balance is hidden from people watching the chain. It is not hidden from Chance, which derives the viewing key to scan it, and the pool shares it with an auditor for legal requests.
* The viewing key reads every amount and counterparty the wallet has ever had in the pool. The pool records it once and it cannot be rotated. It cannot spend funds.
* `strk20_viewing_key_signature` returns the wallet's signature over a fixed derivation message built from a constant domain string and the wallet's address. A client folds that signature into the viewing key. No caller-supplied bytes are signed.

## Private actions over MCP

<Warning>
  `strk20_sign_proof_invocation` and `strk20_relay_private_action` run with no verdict, no limit check and no credit. An agent holding a `wallet`-scoped credential can sign and relay a private action that the wallet's mandate and limits would not allow. Only submission through `escrow_execute` is judged.
</Warning>

A private action is proved first, then submitted. All STRK20 tools are free and, except `strk20_relay_status`, need the `wallet` scope.

<Steps>
  <Step title="Check the relay">
    `strk20_relay_status` reports whether the relay key is configured, whether the relay service is reachable, and whether the key is accepted for private actions. Skip this if you will submit through `escrow_execute`.
  </Step>

  <Step title="Get the relay fee">
    To relay, call `strk20_pool_fee` (optional `feeToken`, default STRK). It returns a withdraw action that pays the relayer from the private balance. Add it to your actions before proving. A proof commits to its actions, so a fee cannot be added afterwards.
  </Step>

  <Step title="Serialize the actions">
    Build the arguments of the pool's `compile_actions(user_addr, user_private_key, client_actions)` as felts. The first felt must be the wallet's own address. The second is the wallet's viewing key, so Chance sees it when it signs.
  </Step>

  <Step title="Sign and prove">
    `strk20_sign_proof_invocation` takes `wallet` and `compileActionsCalldata`. It builds the invocation against the pinned pool address, signs it with the wallet's key, sends it to the proving service, and returns the calldata it signed, the signature and the proof (`proof.proof` and `proof.proof_facts`). It never signs a hash supplied by the caller. It signs with Chance's authorization on the wallet, so it works on autonomous wallets only. The proof expires about five minutes after it is produced.
  </Step>

  <Step title="Submit">
    Use one of the two paths below before the proof expires.
  </Step>
</Steps>

| | `escrow_execute` | `strk20_relay_private_action` |
| - | - | - |
| Inputs | `starknetCalls` with the pool's `apply_actions` call, and `starknetProof: { facts, data }` from `proof_facts` and `proof` | `call` (the `apply_actions` call), `proof`, `proofFacts`, and `feeToken` matching the fee quote |
| Judged and limited | Yes. Simulated, checked against limits, judged. 1 credit. | No |
| Who calls the pool | The wallet. The pool's flat fee is taken from the wallet's public address, and the wallet pays gas in STRK. | The relayer (AVNU paymaster, `sponsored_private` mode). The relayer pays gas; its fee comes from inside the proof. |
| Returns | A proposal result | `txHash` and `trackingId` |

The proof is not stored with a proposal. Through `escrow_execute`, a private action completes only when it executes immediately: an autonomous wallet, an `ALLOW` and a clean simulation. A held proposal cannot be completed from its approval link; propose again with a fresh proof.

## What stays visible

A private swap goes through an anonymizer contract (AVNU or Ekubo) that trades against public liquidity. That hides which wallet made the trade. It does not hide the trade's size.