From zero to your first cited answer

Get an agent indexing your documents and answering questions over them — paid per call in USDC — in a few commands. No signup, no dashboard, no API key: just a wallet.

Prerequisites

Node 20+ — for @agentrag/cli and @agentrag/client.
Point at the API — AGENTRAG_ENDPOINT defaults to https://api.agentx402.ai; only set it to override.
Optional: spend caps — AGENTRAG_MAX_SPEND_USD (per call) and AGENTRAG_MAX_SESSION_SPEND_USD (cumulative) refuse any op above them. A malformed value fails closed, never unlimited.
Something to index — a docs URL, a same-origin crawl root ending /**, or raw text. It does not have to be public: ingest takes documents directly.

node --version # v20 or newer
export AGENTRAG_ENDPOINT=https://api.agentx402.ai # optional — this is already the default
export AGENTRAG_MAX_SPEND_USD=0.05 # optional — refuse any single call above this

Index, then ask

AgentRAG is wallet-native — no signup, no API key. Leave AGENTRAG_PRIVATE_KEY unset and it mints and manages a local wallet for you on first use; export your own key instead and it uses that. (An opt-in account-key mode — an ak_… bearer funded out-of-band via AgentKV — covers managed wallets that can't sign; see the CLI docs for that path.)

1
Get a wallet.

No wallet new command to run first — the CLI mints a local keypair on the first paid call and persists it (0600) under ~/.agentrag/wallet.json. agentrag wallet is free and purely local: it prints the address to fund and the file to back up, and never the private key.
```
npx @agentrag/cli wallet
# → the address AgentRAG pays from, and the keystore file backing it.
# No AGENTRAG_PRIVATE_KEY set? A local keypair is minted on first use and saved
# 0600 to ~/.agentrag/wallet.json. Fund the printed address, then make a call.
```
Bring your own wallet instead? export AGENTRAG_PRIVATE_KEY=0x… and AgentRAG uses it — no local key is minted.
2
Fund it.

Send USDC on Base to the printed address. Asking is $0.008; indexing is $0.005 per page, up to 200 pages a call, with every page that fails to fetch refunded as credits. So a 20-page docs site costs about $0.10 to index once, and each question after that is the flat ask price. No onramp helper ships in the CLI — send USDC to the address directly (e.g. awal send).
```
awal send 5 0x… # or send USDC to the printed address any other way
```

Index, then ask.

Index your sources into a named collection, then ask questions of it. Same service from every surface — pick the one that fits your agent.

Skipping the separate ingest works too: an ask that names --sources indexes them first, on demand. Just know it is then quoted as a composite — the ask plus the pages it had to index — not the flat $0.008. If a large ingest would take a while, the call returns a pending status instead of an answer; pass --wait (or use askAndWait) to block through it and get the real answer back in one command.

agentrag ingest --sources "https://example.com/docs/**" --collection docs
agentrag ask "what does the refund policy say?" --collection docs   # flat $0.008
agentrag status docs                                                # free — counts, model, expiry
agentrag extend docs --days 30                                      # buy 30 more days

import { AgentRag } from "@agentrag/client";

const rag = new AgentRag({ signer, endpoint, maxSpendUsd: 0.05 });

// index + answer in one call; askAndWait polls through the ingest for you
const { collection, chunks } = await rag.askAndWait("what changed in v2?", {
  sources: ["https://example.com/docs/**"],
});

// ask again against the same collection — no re-index, flat ask price
const more = await rag.ask("and in v3?", { collection });

// Claude Code / Cursor / any MCP client — add to your config:
{
  "mcpServers": {
    "agentrag": {
      "command": "npx",
      "args": ["-y", "@agentrag/cli", "mcp"],
      "env": {
        "AGENTRAG_PRIVATE_KEY": "0x…",
        "AGENTRAG_ENDPOINT": "https://api.agentx402.ai",
        "AGENTRAG_MAX_SPEND_USD": "0.05",
        "AGENTRAG_MAX_SESSION_SPEND_USD": "1.00"
      }
    }
  }
}

Before you ship

Collections expire — and asking keeps them alive

A collection lives 7 days, and every ask or ingest that touches it slides that window back out to a full 7 days. A corpus you query regularly never expires on its own, so extend is for the case you'd otherwise lose: a collection you want to keep but won't be querying for a while. It buys 30/60/90 days, priced on the collection's real size — $0.010 per 5,000-chunk block per 30 days. status tells you the expiry for free.

Don't index secrets

A collection is stored and indexed in the clear server-side — retrieval can't rank text it can't read, so unlike AgentKV there is no client-side encryption and no zero-knowledge claim here. Index docs, product content, anything you'd hand to the service. For state the server must never see, use AgentKV instead.

Cap the spend — especially on a composite ask

Set maxSpendUsd in the client (or AGENTRAG_MAX_SPEND_USD for the CLI and MCP) for a per-call ceiling, plus AGENTRAG_MAX_SESSION_SPEND_USD for a cumulative one; either is checked before the payment is signed, and an over-cap op throws rather than silently capping. The per-call cap matters most on an ask that names new sources: its authorized ceiling scales with the pages it would index, so a cap sized for a flat ask will refuse a large on-demand ingest. That's the cap working — raise it deliberately, or pre-warm with an explicit ingest first.

Pick the model once

A collection's embedding model is fixed when it is created, because vectors from two models aren't comparable and mixing them would quietly degrade every later query. Ingesting into an existing collection with a different model is rejected outright (model_mismatch), before anything is charged. Omit model to inherit whatever the collection already uses.

See pricing Explore AgentRAG →What is x402 →