agentx402
Get started →

AgentKV

Encrypted, wallet-authenticated, pay-per-request key-value storage — your agent's long-term memory, private by default.

What makes it different

Zero-knowledge

The server never sees your data. Values and key names are AES-256-GCM encrypted client-side — under a key derived from your wallet, or one you supply — and the server stores only ciphertext, addressed by opaque digests.

Isolated by namespace

One agent can't read — or even address — another's keys. Each wallet, or opt-in ak_… account key, is its own strongly-consistent namespace.

Exactly-once

A retry never double-charges or double-writes. Payment settles before the write, and a retry that reuses its idempotency key lands exactly once.

Scales by wallet

Throughput grows with your fleet. Every wallet is an independent namespace — a million agents run as a million parallel stores, no shared bottleneck — and idle wallets cost almost nothing.

Bounded spend

Spend is capped per call and per session. maxSpendUsd (AGENTKV_MAX_SPEND_USD) refuses any single operation over the cap; maxSessionSpendUsd (AGENTKV_MAX_SESSION_SPEND_USD) bounds what a runaway agent can spend in total.

Two ways to hold a namespace

Your wallet is your namespace by default; an opt-in account-key mode lets a managed wallet own one instead. Either way, values are encrypted under a key only you hold.

Wallet-native

The default. Your wallet is your namespace — no signup. The agent authenticates with its wallet signature and pays per request in USDC over x402; identity and payment are one key.

Account-key

Opt-in, for a managed or embedded wallet — like awal — that can't expose a signing key. A client-generated ak_… bearer token owns the namespace, and any wallet can fund it: payer funds, bearer owns. Values still take a local encryption key, so they stay zero-knowledge. Both the token and that key are unrecoverable — back them up.

Fund the account once with a deposit — a fresh ak_… has no account until then, so its first paid op comes back 402 account_not_provisioned carrying a payment challenge you can settle to provision it (the free routes answer 401 instead). Then set AGENTKV_TOPOFF=awal and the client keeps it funded automatically, topping off from awal when credits run low or on an insufficient-credits 402. Prefer to pay per operation instead? Set AGENTKV_INLINE=awal and each set/get settles its own price on-chain inline — no balance to maintain.

agentkv account new  // mints ak_… + a local encryption key
export AGENTKV_ACCOUNT_KEY=ak_...  AGENTKV_ENCRYPTION_KEY=0x...

// provision the account once — a fresh ak_ gets a payable 402 until funded
awal x402 pay https://api.agentx402.ai/v1/account/deposit \
  --headers '{"Authorization":"Bearer ak_..."}'

export AGENTKV_TOPOFF=awal  // then keep it funded from awal
agentkv set mykey '{"hello":"world"}'  // debits prepaid credits

The API

Six operations. Values up to 256 KB, with a sliding or strict TTL.

Prepay and pay a tenth — 90% off. The rates above are pay-as-you-go. Deposit once and every op bills from prepaid credits instead: $0.0005 per write, $0.0003 per read. See pricing → 

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

const kv = new AgentKV({ privateKey, endpoint, maxSpendUsd: 5 }); // hard cap: $5 / op

// store encrypted; expires in 1 day, strict TTL
await kv.set("session:plan", plan, { ttl_days: 1, strict_ttl: true });

const saved = await kv.get("session:plan"); // decrypted locally
await kv.deposit(5);                          // pre-pay 50,000 credits
await kv.delete("session:plan");

Four ways to use it

The same store behind every entry point — pick the one that fits your agent.

New here? Start with the Quickstart.

See pricingView on GitHub →