Set up Oak: install, connect and ask

Install once. Connect your assistant. Your wallet creates itself.

Before you start

Install Oak 0.2.1 and subscribe.

Subscriptions are open in Oak 0.2.1. Read tools need no identity or subscription; hosted actions require a verified ERC-8004 identity and an active subscription. Official $OAK address: 0x6511c233790Ec10f7d673c64DC82C3F941D57828. Pons page: https://ponsfamily.com/launchpad/0x6511c233790ec10f7d673c64dc82c3f941d57828. Plan availability follows account.phase: no-hold on the curve, neither plan during warmup, and both plans when ready with a valid price note.

Install version 0.2.1; check with oak --version. Human confirmation is on by default. Approve identity setup and the recurring subscription cost separately.

Keep your assistant open on your computer. A website visit does not connect a wallet.

1. Install Oak

Use Node.js 22.12.0 or newer. In your terminal:

npm install -g @oakagentkit/addon@0.2.1

The add-on includes the core package. Both are published. Installing 0.2.1 connects the tools; actions also need a verified identity and an active subscription.

Prefer to ask your agent? Copy this prompt

Set up Oak for this AI agent using Node.js 22.12.0 or newer. Install @oakagentkit/addon@0.2.1 and connect the local MCP command oak mcp. Call account and tell me the public wallet address and network. Ask me to fund ETH for network fees and USDG, then re-check balances. Do not run oak init or oak export, read wallet/key files, or ask for keys or recovery words. Explain public identity registration and recurring subscription costs; get my approval before either.

2. Connect your assistant

Choose your client, add Oak, then start a fresh session. MCP is a connection for AI tools; the local command is oak mcp.

Connect directly with Node.js 22.12.0 or newer and npm on your PATH. These shortcuts run npx -y @oakagentkit/addon@0.2.1 mcp; no global Oak install is needed.

Add to Cursor Install in VS Code

For Claude Code, run these two commands inside Claude:

/plugin marketplace add OakAgentKit/oak
/plugin install oak@oak-agent-kit

Approve your app’s install prompt and start a fresh session. If you already added Oak manually, use that connection or remove the duplicate before installing. Registration and paid subscriptions still need separate approval.

Claude Code

Run in your terminal after installing Oak.

claude mcp add oak -- oak mcp

Codex

Add to your Codex MCP configuration.

[mcp_servers.oak]
command = "oak"
args = ["mcp"]

Gemini

Add to your Gemini MCP settings.

{"mcpServers":{"oak":{"command":"oak","args":["mcp"]}}}

Cursor

Add to your Cursor MCP configuration.

{"mcpServers":{"oak":{"command":"oak","args":["mcp"]}}}

Grok / other MCP hosts

Use a host that supports local stdio MCP servers.

{"mcpServers":{"oak":{"command":"oak","args":["mcp"]}}}

3. Your wallet is automatic

First MCP or CLI wallet use creates it on your computer. Later runs reuse it. Ask your agent:

Call account. Show only my public wallet address and network. Do not send a transaction.

You can also display the public address in your terminal:

oak address

Your private key never leaves your computer. Oak cannot recover a lost key. Backups are optional: oak backup gives guidance. Run oak init or oak export only in your own terminal, never through the agent. Never paste a key or recovery words into chat.

4. Fund and subscribe through Oak

After installing Oak 0.2.1, send ETH for network fees and USDG for subscription payments to the public wallet address. Use the network it reports: Robinhood Chain mainnet is 4663. Then ask:

Re-check balances and show the ETH and USDG amounts on my selected network. Do not register or subscribe yet.

Read tools need no identity or subscription. Paid actions need both a public agent identity and an active subscription.

Approve identity and subscription separately

Plan availability follows account.phase: no-hold on the curve, neither plan during warmup, and both plans when ready with a valid price note.

ERC-8004 is a public agent identity. Registration publishes a profile and costs ETH for gas. Linking an existing identity needs no gas; an external owner signs in their own terminal.

Explain oak_setup registration or linking and its cost. Ask for my approval before proceeding. Then call account, explain the available plan and recurring cost, and ask separately before oak_subscribe.

On the launch curve, only no-hold is offered, at 12.333333 USDG per 30 days. After graduation, both plans wait through warmup. When ready, the holder plan costs 9 USDG per 30 days plus the required $OAK holding and one-time sign-up burn.

While oak mcp runs, active subscriptions auto-renew when three days or fewer remain. Prepay is capped at 90 days ahead. Cancelling with oak cancel ends access immediately and forfeits remaining paid days.

Read the complete pricing terms

5. Make your first request

Start with a read:

Call account, balances and positions. Show my network, balances and subscription status in plain English. Do not send any transactions.

Then try a quote, without sending a transaction:

Find USDG and ETH with find_token. Quote 10 USDG (10000000 base units) to ETH with slippageBps 50. Explain the expected and minimum output. Do not swap.

More prompts to paste; approve each action after its preview:

What can you do with Oak? Group the tools by project.
Show my Oak wallet address and balances. Do not send anything.
Quote a swap of 5 USDG to ETH with the best route. Show the preview and do not swap yet.
Lend 10 USDG on Priors. Show me the preview before anything is signed.
Deposit 10 USDG into a Steakhouse vault. Show me the preview first.
Show my open positions across every project.

One click selects a whole command or prompt. Then copy it: Cmd or Ctrl + C, or long-press on a phone.

For a later action, inspect the preview, confirm the exact action, then let the local wallet sign. Built approvals are exact. Simulations exclude gas and cannot prove external settlement or whether a token can later be sold.

Explore the project tools · Read the custody boundaries

Need a hand?

If actions are paused, call account to check identity, subscription and plan phase. For connection problems, check your client connection and service notices from @OakAgentKit on X. Do not change networks or fund another address to work around it.

Error messages and fixes

Use the exact error message below to resolve identity, funding, subscription or price-note problems.

Every error message in Oak is a plain sentence naming the state and the exact command to fix it:

State / Message	Cause	Exact Action to Fix
`run this in your own terminal, not through the agent`	`oak init` or `oak export` was invoked without an interactive TTY.	Run `oak init` or `oak export` directly in your own system terminal.
`Run oak setup to register or link an ERC-8004 identity first. Reads remain available; actions are paused.` / `Verify or link an ERC-8004 identity with oak setup. Reads remain available, actions paused.`	An action tool was called before setting up an ERC-8004 identity (`identity.ts` and the Oak server).	Run `oak setup link <agentId>` (no ETH) or `oak setup register` (needs ETH), or call `oak_setup`.
`Identity changed, expired or link revoked. Run oak setup link <agentId> with the current owner to verify or link it again. Reads remain available; actions are paused.`	The linked ERC-8004 NFT was transferred or burned, or the link was revoked (`identity.ts`). Local `identity` config was cleared.	Run `oak setup link <agentId>` with a fresh signature from the current NFT owner, or register a new agent ID with `oak setup register`.
`Identity status is unavailable. Please try again. Reads remain available; actions are paused.`	The server or RPC could not verify identity status during an outage (`identity.ts`). Saved local `identity` is preserved.	Keep your config as-is and retry the action once the RPC or server is reachable; read tools continue to work.
`This wallet does not own that agent ID. Ask the current owner to sign the link in oak setup link <agentId>.` / `Owner signature does not match the current agent owner. Ask the current owner to sign with oak setup link <agentId>.`	Direct verification was attempted for an `agentId` owned by another wallet, or the pasted signature was not from `ownerOf(agentId)`.	Run `oak setup link <agentId>` in your terminal and sign the EIP-712 challenge with the wallet that currently owns `<agentId>`.
`The identity challenge expired. Run oak setup link <agentId> again for a fresh owner signature.`	More than 5 minutes passed before submitting the owner's EIP-712 signature, or the challenge nonce was already consumed.	Run `oak setup link <agentId>` again and paste the fresh signature within 5 minutes.
`Wrong identity network or registry. Set OAK_NETWORK and OAK_CHAIN_ID to match the owner’s agent, then run oak setup again.`	The identity registry or chain ID does not match the configured network (`4663` mainnet vs `46630` testnet).	Align `OAK_NETWORK` and `OAK_CHAIN_ID` in `~/.oak/config.json`, then run `oak setup`.
`OAK_NETWORK disagrees with the local config; set the network in the config explicitly.` / `Set OAK_NETWORK to mainnet (4663) or testnet (46630).`	Environment variables and `~/.oak/config.json` specify different networks (`mainnet` vs `testnet`), or `OAK_NETWORK` has an invalid value.	Set `OAK_NETWORK`, `OAK_CHAIN_ID`, and `OAK_RPC_URL` to the same network (`4663` or `46630`) in `~/.oak/config.json`.
`needs ETH for network fees: send ETH to <address> on chain <chainId>.` / `Needs ETH for network fees: send ETH to <address> on chain <chainId>.`	Wallet ETH balance cannot cover `value + gas * maxFeePerGas` (including 25% gas headroom) in `sender.ts`, or is `0` in `subscribe.ts`.	Send native ETH on the named chain to `<address>` (`oak address`) and retry.
`No active subscription. Use oak subscribe --plan nohold; only the no-hold plan at 12.333333 USDG per 30 days is open.`	Action tool called while `plan == "none"` during `curve` (checked by the Oak server).	Run `oak subscribe --plan nohold`.
`No active subscription. The pool is warming up; both plans wait for 30 minutes of history before oak subscribe.`	Action tool called while `plan == "none"` during `warmup` (checked by the Oak server).	Wait until the pool has 30 minutes of history, then run `oak subscribe`.
`No active subscription. Use oak subscribe --plan holder or oak subscribe --plan nohold and top up USDG for the subscription.`	Action tool called while `plan == "none"` during `ready` (checked by the Oak server).	Top up USDG (and `$OAK` if joining holder) and run `oak subscribe --plan holder` or `oak subscribe --plan nohold`.
`No subscription. Use oak subscribe --plan holder or oak subscribe --plan nohold.`	`oak renew` / `ensureSubscribed` called when the wallet has no subscription record (`renew.ts`).	Run `oak subscribe --plan holder` or `oak subscribe --plan nohold`.
`Holder plan is closed during the curve; use oak subscribe --plan nohold.`	`$OAK` is in the `curve` phase (`phase != 2` on Pons) when running `oak subscribe --plan holder`.	Join with `oak subscribe --plan nohold` at the `12.333333 USDG` floor, or wait until `$OAK` graduates and completes warmup.
`Price warmup: wait until the pool has 30 minutes of history, then retry.`	`$OAK` graduated (`phase == 2`), but the v4 pool is under 30 minutes old (`history_too_thin`).	Wait until the pool is 30 minutes old; both plans wait during warmup and sign nothing.
`Subscription is paid; renewal is not due.`	More than 3 days remain before `paidUntil` and access checks pass (`renew.ts`).	No action needed; renewal opens when `<= 3 days` remain (prepaying is capped at 90 days ahead).
`subscription ended <date>; keep the agent running to renew or run oak renew`	`paidUntil` is in the past (checked by the Oak server). Read tools still work; action tools are paused.	Top up USDG (and ETH for gas) if needed, then run `oak renew` or start `oak mcp`.
`hold at least <N> $OAK (you hold <M>)` / `Buy back <count> OAK base units (token <oak>, decimals 18) to restore access.` / `Needs <oakRequired> OAK base units (token <oak>, decimals 18). Buy back OAK and retry.`	Holder-plan wallet's `$OAK` balance is below its tracked `signupOakCount` (the Oak server, `renew.ts`) or below the required count at sign-up/migration (`subscribe.ts`).	Buy back `$OAK` to at least the required count; for an active subscription, access resumes immediately on the next call with no new fee.
`Renewal/payment needs <amount> USDG base units (token <usdg>, decimals 6). Top up and run oak renew; tools are paused until payment succeeds.`	Wallet USDG balance is below the subscription or renewal price (`subscribe.ts`).	Send USDG (`0x5fc5360d0400a0fd4f2af552add042d716f1d168`, 6 decimals) to your wallet and run `oak renew` (or `oak subscribe`).
`your paid days carry over with oak renew when it is due`	Wallet is an active holder on a retired subscription contract and is listed in the grandfather Merkle tree, but tried to run `oak subscribe` (`subscribe.ts`).	Do not run `oak subscribe` (which would forfeit old paid days). Wait until `<= 3 days` remain and run `oak renew` to migrate at your recorded post-burn count with zero burn.
`Wallet journal is unresolved; wait for the pending transaction before a new action.`	A previously signed transaction in `~/.oak/<address>.pending.json` has not yet been confirmed or reconciled (`sender.ts`).	Run `oak renew` (or start `oak mcp`), which reconciles or fee-bumps the identical call at the same nonce before starting a new action.
`Wallet journal is unreadable or invalid; resolve it before a new action.`	`~/.oak/<address>.pending.json` or `.cleared.json` failed integrity, ownership, mode (`0600`), or signature validation (`journal.ts`).	Inspect `~/.oak/` permissions (`0700` directory, `0600` files owned by your user) and resolve the corrupted journal file after verifying on-chain nonces.
`Payment failed or remains pending; tools are paused. Run oak renew to reconcile the wallet journal before another payment.`	A subscription payment threw a sender exception leaving the journal to be checked (`subscribe.ts`).	Run `oak renew` to reconcile the wallet journal before attempting another payment.
`Already subscribed; use oak renew, or oak cancel before switching plans.`	`oak subscribe` was called while the wallet already has an active plan on the current contract (`subscribe.ts`).	Use `oak renew` to extend the current plan, or run `oak cancel` (which ends access immediately and forfeits remaining paid days) before running `oak subscribe --plan <holder\|nohold>`.

Run oak init --recover in your own terminal to restore an exported private key or legacy 24-word backup on a new computer. To replace an existing wallet, use oak init --recover --replace; Oak preserves an encrypted backup and asks you to confirm the recovered address. Never enter recovery words in an agent chat, arguments, environment variables or MCP tools.

New automatic wallets work with a persistent OS keychain or an owner-only random file key. Existing passphrase wallets are unchanged and still require terminal unlock. Never pass a passphrase through MCP, argv or environment variables. See headless wallet guidance for legacy migration options.

Mainnet uses https://api.oakagentkit.org by default. Override it with oak config set OAK_SERVER_URL <https-url> or OAK_SERVER_URL; testnet requires an explicit matching service URL. Configure the published deployment addresses and your RPC before starting MCP.

Transactions reported as “awaiting finality” keep their signed journal evidence until final. New actions wait for reconciliation; a removed receipt is recovered at the same nonce, or an expired call has its nonce replaced with a zero-value self-transfer. Do not delete journal files to force a retry. If a sequence stops after approval, the error lists token, spender, base-unit amount and chain. The next action previews and revokes the remaining allowance before new work; keep ETH available for cleanup. You can also call approve(spender, 0) on that token in your own wallet on the named chain.

Price notes require an ETH/USD pool observation no older than 30 minutes and a current 30-minute OAK trade window. Missing, future-dated or stale sources refuse note issuance with a retry explanation; an old Uniswap observation extrapolated by observe(0) does not qualify.

Adding your own Robinhood Chain RPC URL, such as a free or paid Alchemy key that permits full-history log queries, can make Oak's one-time approval check take seconds (14 requests in 2.003 seconds in the recorded check). Set OAK_CENSUS_RPC_URL locally for the history check, or OAK_RPC_URL for all chain calls, then restart Oak; never paste a keyed URL into chat. Range-limited plans take longer. Generic swaps use direct Uniswap routes during catch-up; aggregator routes unlock when coverage is complete and still require a tracing RPC.

Automatic approval budget: In owner-selected auto mode, automatic approvals default to a 50 USD budget per local calendar day. Actions above the remaining budget, without a fresh USD value, or with unavailable usage records require human approval. Ask mode requires confirmation. This budget does not cap spending that a person explicitly approves.

Set up