Set up

Requires Node.js 22 LTS (>=22.12.0 <23). Install the add-on globally from npm at release (or build from the workspace below during pre-launch) with:

Run oak init in your own terminal, never through the agent:

oak init

What happens during oak init:

1. Oak checks that stdin and stdout are attached to a terminal (isTTY). Remember that setup is trusted because you run it in your own terminal, not because a terminal exists (an agent with shell access can allocate a PTY). Running oak init yourself keeps your recovery phrase out of the AI's prompt, tool outputs, and logs.
2. Oak generates a 24-word recovery phrase locally and prints it once. Write the words down offline.
3. Oak prompts you (with hidden input) to confirm three randomly selected words from your phrase.
4. Oak prints the default region notice and not affiliated with Robinhood disclosure, encrypts the private key with AES-256-GCM into ~/.oak/wallet.enc (mode 0600 in ~/.oak mode 0700), and stores the 32-byte encryption key in your OS keychain (macOS Keychain, Windows Credential Manager, or Linux persistent Secret Service).
5. If a persistent OS keychain is unavailable, Oak prompts you to set a passphrase (at least 12 characters) and derives the encryption key with scrypt (N=131072, r=8, p=1). With passphrase storage, unlocking requires your terminal each time.

Your private key never leaves your computer, and Oak cannot recover a lost key.

Store your configuration in ~/.oak/config.json (mode 0600) using oak config set <key> <value> or pass matching environment variables.

Oak targets Robinhood Chain mainnet (OAK_NETWORK=mainnet, chain ID 4663, 0x1237) by default. To test Oak's own contracts and ERC-8004 identity on Robinhood Chain Testnet (46630, 0xb626), opt in explicitly with OAK_NETWORK=testnet and OAK_CHAIN_ID=46630:

# Mainnet (default: OAK_NETWORK=mainnet, chain ID 4663)
oak config set OAK_NETWORK mainnet
oak config set OAK_CHAIN_ID 4663
oak config set OAK_SERVER_URL https://api.oakagentkit.org  # optional mainnet override
oak config set OAK_RPC_URL <your-keyed-robinhood-chain-4663-rpc-url>
oak config set OAK_SUBSCRIPTION_ADDRESS <subscription-contract-address>
oak config set OAK_USDG_ADDRESS 0x5fc5360d0400a0fd4f2af552add042d716f1d168
oak config set OAK_TOKEN_ADDRESS <canonical-oak-token-address>
oak config set OAK_ORACLE_ADDRESS <oracle-contract-address>
oak config set OAK_ETH_USDG_POOL_ADDRESS 0x52e65B17fB6E5BA00Ed806f37Afcd2DaA50271Ca

For Robinhood Chain Testnet (46630) opt-in:

Use a matching testnet Oak server and testnet contract addresses for every required setting above. The four commands below alone are not a complete deployment configuration. Testnet exposes basic tools and ERC-8004 identity tools; swap routes and the other ecosystem modules are not configured there.

oak config set OAK_NETWORK testnet
oak config set OAK_CHAIN_ID 46630
oak config set OAK_RPC_URL <your-robinhood-chain-testnet-46630-rpc-url>
oak config set OAK_USDG_ADDRESS 0x7E955252E15c84f5768B83c41a71F9eba181802F

Network safety rules enforced at startup:

• If OAK_NETWORK, OAK_CHAIN_ID, or any deployment address environment variable disagrees with ~/.oak/config.json, Oak refuses to start (OAK_NETWORK disagrees with the local config; set the network in the config explicitly.).
• Do not mix mainnet (4663) and testnet (46630) RPCs or pin a mainnet contract address in a testnet config (Set OAK_NETWORK to mainnet (4663) or testnet (46630). and Set OAK_CHAIN_ID to <selectedChainId> in the local deployment config.).

Optional settings:

• OAK_RPC_URL_<chainId>: RPC endpoint for an inbound Relay origin chain (for example, OAK_RPC_URL_8453 for Base or OAK_RPC_URL_42161 for Arbitrum when calling relay_bridge_in).
• OAK_RETIRED_SUBSCRIPTION_ADDRESSES: Comma-separated retired subscription contract addresses, newest first.
• OAK_FINALITY: Confirmation mode (finalized by default, safe, or a positive integer block count).
• profile: JSON string for ERC-8004 agent identity registration (oak setup register or oak register).
• grandfather: JSON string containing the OakGrandfather/v1 Merkle tree when migrating from a retired subscription contract.

Wallet private keys and mnemonics are rejected by oak config set.

Every supported agent connects to Oak over stdio by running oak mcp. On startup and once every hour, oak mcp reconciles any pending local journal entries, verifies your ERC-8004 identity status, and checks whether your subscription renewal is due. Read tools work immediately; action tools require a verified ERC-8004 identity and an active subscription.

claude mcp add oak -- oak mcp

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

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

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

command: oak
args: mcp

Step 1: Set up your ERC-8004 identity (oak setup)

Every action tool requires a verified ERC-8004 agent identity on the pinned IdentityRegistry (0x8004A169FB4a3325136EB29fA0ceB6D2e539a432) plus an active subscription. Read tools (find_token, balances, price, quote, preview, history, positions, account, and module reads) stay open without an identity or subscription.

Before registering a new identity, run oak address and send ETH for gas on your configured network. Linking an existing identity needs no ETH. Replace the example profile's name, description, and image URL with your own before registering.

Run oak setup in your terminal (or call the local MCP tool oak_setup):

# Interactive prompt in your terminal:
# "Identity first: type register (public registration, needs ETH), or link <agentId> (owner signature, no ETH):"
oak setup

# Option A: Link an existing ERC-8004 agent ID (no ETH needed, no on-chain transaction)
oak setup link <agentId>

# Option B: Register a new ERC-8004 agent ID on-chain (needs ETH for gas)
oak config set profile '{"type":"https://eips.ethereum.org/EIPS/eip-8004#registration-v1","name":"my-agent","description":"My Oak agent","image":"https://example.com/my-agent.png","services":[],"x402Support":false,"active":true,"registrations":[]}'
oak setup register
# Pass --no-tag to omit the default oak.registrar marker:
oak setup register --no-tag

• How oak setup link <agentId> works (gasless): If your agent wallet does not own <agentId> directly, oak setup link <agentId> prints a single-use 5-minute EIP-712 OakIdentityLink challenge (audience: "oak-identity-link/v1") in your terminal and prompts with hidden input for the current NFT owner's signature. Never paste a private key or recovery words. The server checks ownerOf(agentId) at a canonical block, stores the verified link (linkId), and never stores the raw signature. If the agent wallet itself already owns <agentId>, it signs locally without prompting.
• How oak setup register works (on-chain): Mints a new ERC-8004 identity NFT to your agent wallet on IdentityRegistry, verifies ownership with the server, and saves { chainId, registry, agentId } in ~/.oak/config.json.

Step 2: Fund the agent wallet and subscribe

Print your agent's wallet address:

oak address

Send funds directly to that address on your configured network: Robinhood Chain mainnet (4663), or testnet (46630) if selected:

1. ETH for network gas fees (required for on-chain registration, subscribing, and trading; not required for oak setup link <agentId>).
2. USDG (0x5fc5360d0400a0fd4f2af552add042d716f1d168 on mainnet, 0x7E955252E15c84f5768B83c41a71F9eba181802F on testnet 46630, 6 decimals) for your monthly subscription and any swaps, vault deposits, or orders.
3. $OAK (18 decimals) if you choose the holder plan: you need only the entry-price count N at sign-up. Joining has a one-time sign-up burn that burns 5% of N (ceil(N * 5 / 100)) from that holding and records the remaining N - burn as your tracked signupOakCount (for example, hold 20,000 $OAK at sign-up, 1,000 $OAK burns, and 19,000 $OAK is tracked while subscribed). In packages/addon/src/subscribe.ts, the add-on reads [count, burn] from quoteHolder, passes maxCount = ceilPercent(count) (at most 1% above count) to subscribeWithAuthorization, and approves the exact quoted burn (approval(this.deployment.oak, contract, burn.toString(), this.deployment.chainId)), never unlimited.

Then subscribe from your terminal:

# Holder plan: 9 USDG per 30 days; hold N $OAK, 5% burns at sign-up, N - burn tracked
oak subscribe --plan holder

# No-hold plan: 9 USDG + (entry price / 6) per 30 days (12.333333 USDG floor), no $OAK required
oak subscribe --plan nohold

First reads and buying a token (find_token → quote → preview → swap)

The TSLA swap example below is for mainnet (4663); testnet has no configured swap routes.

# First read: check subscription status, $OAK held vs required, launch phase, and no-hold price
oak status

# One-call portfolio reads: balances batches token reads via Multicall3; positions queries all 25 modules in one call
oak call balances '{}'
oak call positions '{}'

# First action: buy a token in four steps (find_token -> quote -> preview -> swap)
# 1. Discover or verify a token by name, symbol, or address on chain 4663
oak call find_token '{"query":"TSLA"}'

# 2. Get a 60-second swap quote across KyberSwap, Velora, and Pons launch curves using verified symbols
#    (ETH, USDG, WETH, USDe, OAK, or official stock tickers) or a verified token address.
#    Quotes warn when price impact exceeds 2% against fresh reference prices.
oak call quote '{"from":"USDG","to":"TSLA","amountIn":"10000000","slippageBps":50}'

# 3. Preview an unsigned transaction sequence via eth_simulateV1
#    (swap reuses a matching preview from the same block within 12 seconds so it does not re-simulate twice)
oak call preview '{"txs":[...]}'

# 4. Execute the swap by quoteId (builds exact approvals only, never unlimited; signs locally and broadcasts)
oak call swap '{"quoteId":"<quoteId>"}'

# Manage opt-in declarative project recipes (data-only, as-is)
oak recipes add <npm-pkg-or-local-path>
oak recipes list
oak recipes remove <project>

Unlinking, transfers, and outages

# Unlink from the linked agent wallet (gasless; clears local identity, pauses actions, keeps reads open)
oak identity unlink

# Or revoke a link as the current NFT owner by linkId (prompts for owner EIP-712 unlink signature in terminal)
oak identity unlink --owner <linkId>

• Unlink (oak identity unlink or MCP tool oak_identity_unlink): Immediately revokes the link in the server store and removes identity from ~/.oak/config.json. Read tools remain available; action tools pause until you run oak setup again.
• NFT transfer or burn: On every action tool call, the server verifies ownerOf(agentId) and checks for any Transfer log since linkedBlock at a canonical block. If the ERC-8004 NFT was transferred or burned, linked action access ends immediately, the add-on clears the local identity config, and reads stay open.
• Server or RPC outage: If identity verification cannot reach the chain or server (Identity status is unavailable. Please try again. Reads remain available; actions are paused.), the add-on keeps your saved identity in ~/.oak/config.json and asks you to try again once the service recovers. Read tools stay open.

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

Run oak init --recover in your own terminal to restore your 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.

For stdio MCP, Oak needs an accessible persistent OS keychain (Linux: Secret Service in the same unlocked user/D-Bus session as the MCP client). A passphrase-only wallet currently supports interactive CLI commands in your own terminal; it cannot start oak mcp through a pipe. Do not send the passphrase through MCP or store it in argv/environment variables. To enable MCP for an existing fallback wallet, first configure a persistent keychain, then restore with oak init --recover --replace yourself in your terminal and confirm the address. Keep the old encrypted backup and recovery words offline.

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.