From zero to your first encrypted write

Create a wallet.

Generate a fresh keypair. The private key prints once and is never stored — capture it and export it for the CLI and client.

agentkv wallet new
# → { "address": "0x…", "privateKey": "0x…" }  — shown once, not saved
export AGENTKV_PRIVATE_KEY=0x…

Store the private key in a secret manager — it's shown once and can't be recovered.

Fund it.

agentkv fund prints a card-to-USDC onramp URL that sends USDC to the wallet — the command makes no payment itself. Or send USDC to the address directly (e.g. awal send). Then pay per op — a write is $0.005, a read $0.003 — or run agentkv deposit <usd> to pre-pay credits (minimum $1) at a tenth the price.

agentkv fund # prints a card → USDC onramp URL (makes no payment itself)
# — or send USDC straight to the wallet address:
awal send <amount> <address>
# — or pre-pay credits instead of paying per op:
agentkv deposit <usd>

Write & read.

Same store from every surface — pick the one that fits your agent.

agentkv set session:42 '{"step":3}' # encrypted, paid per write
agentkv get session:42 # decrypted client-side

import { AgentKV } from "@agentkv/client";

const kv = new AgentKV({ privateKey, endpoint, maxSpendUsd: 5 });

await kv.set("session:42", { step: 3 }); // encrypts, then pays
const state = await kv.get("session:42"); // → { step: 3 }

// Claude Code / Cursor / any MCP client — add to your config:
{
  "mcpServers": {
    "agentkv": {
      "command": "npx",
      "args": ["-y", "@agentkv/cli", "mcp"],
      "env": {
        "AGENTKV_PRIVATE_KEY": "0x…",
        "AGENTKV_ENDPOINT": "https://api.agentx402.ai",
        "AGENTKV_MAX_SPEND_USD": "5.00"
      }
    }
  }
}

Mint an account key.

Generate an ak_… bearer token plus a local encryption key. The bearer owns the namespace; the encryption key never leaves your machine.

agentkv account new
# → account key:    ak_…
# → encryption key: 0x…  (local — never sent to the server)
export AGENTKV_ACCOUNT_KEY=ak_…
export AGENTKV_ENCRYPTION_KEY=0x…

Both are unrecoverable — back them up. Lose the encryption key and the data can't be decrypted.

Get awal ready.

awal is the wallet that pays. npx [email protected] status signs you in; if its wallet is empty, awal address gives you a deposit address — send it USDC. A brand-new awal wallet also needs a little ETH on Base (~$1) for its one-time smart-account deployment, before it can sign anything, so send that too.

npx [email protected] status # sign in
# if empty: awal address → send USDC, plus a little ETH (~$1, one-time)

Provision: deposit for prepaid credits.

A brand-new ak_… has no account yet — deposit once to provision it (minimum $1, from any wallet — payer funds, bearer owns) at a tenth the pay-per-op price. Set AGENTKV_TOPOFF=awal and the client keeps it topped up automatically as credits run low. This is the economical path for repeat use.

awal x402 pay https://api.agentx402.ai/v1/account/deposit \
  --headers '{"Authorization":"Bearer ak_…"}'
export AGENTKV_TOPOFF=awal # tops off from awal when credits run low

Or skip the deposit — pay per call.

No deposit needed: the first set/get against a never-funded account gets a 402 account_not_provisioned challenge (distinct from an ordinary out-of-credit insufficient_credits) instead of running unfunded — a bare awal pays it out of the box, no AgentKV-specific setup required. Our own CLI and client gate that first payment behind an explicit opt-in instead, since auto-funding it is indistinguishable from funding a typo'd key: set AGENTKV_INLINE=awal to pay each op inline, plus AGENTKV_BOOTSTRAP=1 to let it cover that first challenge too. Skip the flag if the account key is read straight from agentkv account new's own ~/.agentkv/account.json (not re-exported) — a file the CLI wrote itself can't be a typo, so it bootstraps automatically.

export AGENTKV_INLINE=awal    # pay each op inline via x402 — no prepaid credits
export AGENTKV_BOOTSTRAP=1    # opt in to paying the FIRST-ever op too
agentkv set session:42 '{"step":3}' # 402s once (account_not_provisioned), awal pays it

Write & read.

Same store, same surfaces — the client and MCP take the account key and encryption key instead of a private key.

agentkv set session:42 '{"step":3}' # encrypted, paid per write
agentkv get session:42 # decrypted client-side

import { AgentKV } from "@agentkv/client";

const kv = new AgentKV({ accountKey, encryptionKey, endpoint, maxSpendUsd: 5 });

await kv.set("session:42", { step: 3 }); // encrypts, then pays
const state = await kv.get("session:42"); // → { step: 3 }

// Claude Code / Cursor / any MCP client — add to your config:
{
  "mcpServers": {
    "agentkv": {
      "command": "npx",
      "args": ["-y", "@agentkv/cli", "mcp"],
      "env": {
        "AGENTKV_ACCOUNT_KEY": "ak_…",
        "AGENTKV_ENCRYPTION_KEY": "0x…",
        "AGENTKV_ENDPOINT": "https://api.agentx402.ai",
        "AGENTKV_MAX_SPEND_USD": "5.00"
      }
    }
  }
}