> For the complete documentation index, see [llms.txt](https://hinkal-team.gitbook.io/hinkal/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hinkal-team.gitbook.io/hinkal/hinkal-mcp/troubleshooting.md).

# Troubleshooting

<details>

<summary>A deposit fails saying the wallet is unfunded</summary>

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.

</details>

<details>

<summary>Funds seem gone after a restart</summary>

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.

</details>

<details>

<summary>A deposit reverts on broadcast</summary>

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

</details>

<details>

<summary>A withdraw or transfer reports insufficient funds</summary>

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.

</details>

<details>

<summary>A shielded balance looks lower than expected</summary>

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

</details>

<details>

<summary>A hinkal-mcp: command not found</summary>

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

</details>