# ZKDepth agent quickstart

A runnable starting point for an agent that uses ZKDepth with its own wallet. It does what an agent
should do before it signs anything, in order:

1. Reads what ZKDepth publishes: [`/llms.txt`](https://zkdepth.com/llms.txt), the deployment manifest
   (`/deployments/robinhood.json`), the chain constants (`/deployments/robinhood-external.json`) and
   the ABIs `/llms.txt` links. It stops if the two sources disagree about an address.
2. Quotes a swap of native ETH for USDG through the ZKDepth Router (`Router.quoteExactIn`).
3. Plans a deposit into the USDG Vault of the swap's minimum out: the swap with a minimum
   out and a deadline, an exact approval to the vault, and the deposit. Every `to` is checked
   against the deployment files.
4. Simulates the whole plan in one `eth_simulateV1` request, each call after the one before.
5. Sends it, one transaction at a time, only with `--send`. Without it nothing is signed.

ZKDepth never asks for a key, a seed phrase or a signature. The key stays in this process.

## Files

| File | What it is |
|---|---|
| `quickstart.ts` | the script: read, quote, plan, simulate, send |
| `zkdepth.ts` | the pure helpers it uses: the hop encoding, the plan, the published-address table |
| `zkdepth.test.ts` | their tests (`npm test`, no network) |
| `package.json`, `tsconfig.json` | viem is the only dependency |

## Setup

Node 22.18 or newer runs the TypeScript files directly.

```bash
npm install
```

### On a local fork (the default)

The script talks to `http://127.0.0.1:8560` unless `RPC_URL` says otherwise. Start a fork of
Robinhood Chain there with [Foundry](https://getfoundry.sh)'s anvil. The public RPC keeps only
recent state, so fork from an archive RPC, such as your own Alchemy Robinhood Chain URL:

```bash
anvil --fork-url "$ARCHIVE_RPC_URL" --chain-id 4663 --port 8560
```

Then, in another terminal:

```bash
npm start              # read, quote, plan and simulate; nothing is sent
npm run send           # the same, then send the plan on the fork
npm start -- --amount 0.2
```

On a fork with no `PRIVATE_KEY` set, the script makes a throwaway key and funds it with 1 ETH
(`anvil_setBalance`), so it runs with nothing else to set up.

### On Robinhood Chain

Use a wallet of the agent's own, funded only with what it should manage, never your main wallet.

```bash
RPC_URL=https://rpc.mainnet.chain.robinhood.com AGENT_ADDRESS=0xYourAgentWallet npm start
```

simulates the plan for that address without a key. To send it for real, the key comes from the
agent's own environment, and `--mainnet` must be given as well as `--send`:

```bash
RPC_URL=https://rpc.mainnet.chain.robinhood.com PRIVATE_KEY=0x… npm start -- --send --mainnet
```

The script refuses an address that has code on chain (an EIP-7702 delegation, for instance): such
code can forward what the address receives.

| Variable | Default | |
|---|---|---|
| `RPC_URL` | `http://127.0.0.1:8560` | the chain to read, simulate and send on |
| `ZKDEPTH_SITE` | `https://zkdepth.com` | where `/llms.txt` and the deployment files are read from |
| `PRIVATE_KEY` | none | the agent wallet's key; on a local fork a throwaway one is made when unset |
| `AGENT_ADDRESS` | none | simulate for this address without a key |

## What to change first

- The amount (`--amount`, in ETH) and the slippage (`SLIPPAGE_BPS`, 50 = 0.5 %).
- The route: the script quotes one hop through each public ETH/USDG pool. The Router also takes
  ZKDepth's own pools, DLMM pairs and up to three hops: see
  [Routes through the Router](https://zkdepth.com/docs/agents#routes-through-the-router).
- The vault: any vault in the manifest takes the same `deposit(assets, receiver)`. LP, hedged and
  structured vault shares carry 3 more decimals than their asset, so read the vault's own
  `decimals()`, as the script does.

## The rules it keeps

The same as [`/llms.txt`](https://zkdepth.com/llms.txt) lists, and
[Agents and integrations](https://zkdepth.com/docs/agents) explains: its own wallet, every `to`
checked against the deployment files, exact approvals only, a minimum and a short deadline on the
swap, a fresh `previewDeposit` before the deposit (an ERC-4626 deposit takes no minimum), and one
simulation of the whole sequence before anything is signed. A gas estimate is the least that
succeeded on the latest block, so the script sends with 25 % more, as wallets do.

## Limits

The script reads static files from zkdepth.com and talks to the RPC you give it. The public
RPC is rate-limited: keep reads batched (Multicall3) and slow down on a 429. See
[Rate limits](https://zkdepth.com/docs/agents#rate-limits).