Troubleshooting

A deposit fails saying the wallet is unfunded

The wallet starts empty. Ask for your addresses (get_wallet_addresses), send the token you want to deposit plus native gas to the address for that chain, then retry. The error message includes the address to fund.

Funds seem gone after a restart

Your wallet identity lives in mcp-identity.json in the data directory (~/.hinkal by default), so it survives restarts, updates, and reinstalls, the wallet and its shielded balances come back on the next tool call. It is lost only if that file is deleted or the machine is lost. Back it up first with export_wallet_key, and store the output safely it is the only recovery. If you run in an ephemeral environment (e.g. a container), point --dir / HINKAL_DIR at a persistent path so the file isn't wiped.

A deposit reverts on broadcast

The wallet needs the token balance, native gas, and - for ERC-20/TRC-20 - an allowance to the Hinkal contract (the server sets this automatically when it signs). Check the contract with get_contract_addresses and the balance with get_public_balances.

A withdraw or transfer reports insufficient funds

The fee is charged on top of the amount, so the shielded balance must cover amount + fee. The relayer computes and deducts the fee at settlement, there is no quote step, so leave headroom above the amount you want to send.

A shielded balance looks lower than expected

Funds may be stuck in UTXOs from an interrupted deposit-and-withdraw. Check get_stuck_balances and recover with recover_stuck_funds.

A hinkal-mcp: command not found

The CLI isn't on your PATH. Install it globally with npm i -g @hinkal/mcp; on Windows, add %APPDATA%\npm to your PATH.