Getting started

Fund your agent

Your agent pays for each call from a wallet of its own. Two ways to give it one: sign in — no crypto knowledge needed, five minutes — or a keypair you fund yourself if you already use Solana. Either way there is no Citable account: the wallet is the account.

What you will end up with

A wallet only your agent spends from, holding a small USDC balance on Solana mainnet. It needs no SOL — the x402 facilitator pays network fees — and a spend cap that stops it before any call over the limit you set.

Ask your agent to set up a wallet; it runs citable_connect and gives you a link. Or paste this into the chat:

say to your agent

Set up my Citable wallet — run citable_connect and give me the link.

Open the link, sign in with Google or email — the wallet is created for you — use Add funds to add a few dollars, then click Connect to your agent. The page says Connected, the agent pays from that wallet, and you are done: skip to step 5. Top up any time at citable.run/app with the same sign-in.

What the agent stores

A sign-in session on your computer at ~/.config/citable/para-session.json, renewed while the agent is in use and valid for up to 30 days without use. Nothing about you reaches Citable's servers. The browser and the agent must be on the same computer — the link points at a listener on 127.0.0.1. To disconnect, ask the agent to run citable_connect with reset.

Option B · A keypair you fund yourself #

Four steps for people who already hold USDC on Solana.

1 · Give the agent its own keypair

Never hand an agent the key to a wallet you keep money in. Make a fresh one; the whole point is that it can only ever spend what you put in it.

Running citable-mcp? Skip this step

The MCP server creates ~/.config/citable/agent.json itself the first time it starts; ask the agent to run citable_prices and it shows the address. Go straight to step 2, and in step 3 use the explorer link with that address instead of the CLI.

terminal

# 1. Solana CLI (one-time)
sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"

# 2. a keypair for the agent — not your personal wallet
mkdir -p ~/.config/citable
solana-keygen new --no-bip39-passphrase -o ~/.config/citable/agent.json
chmod 600 ~/.config/citable/agent.json

# 3. the address to send USDC to
solana-keygen pubkey ~/.config/citable/agent.json

The last command prints a 44-character address — that is where the USDC goes. Keep it handy for the next two steps.

2 · Send it a few dollars of USDC

Buy USDC wherever you already can — Coinbase, Kraken, Binance, or a wallet app such as Phantom with card checkout — then withdraw it to the address from step 1. Two things matter:

Check	Why
Network: Solana	USDC exists on several chains. Pick the Solana network when you withdraw — USDC sent on Ethereum or Base never arrives here and cannot be recovered by us.
Asset: USDC, not SOL	The agent pays in USDC. SOL is not needed for fees and is not accepted as payment.
Amount: $5 is plenty to start	That is 250 rank checks, or 20 AI-visibility checks, or 500 keyword lookups. Top up when it runs low; there is no minimum balance.

Exchanges usually hold a first withdrawal for a few minutes to an hour. The transfer itself settles in seconds once sent.

3 · Check it arrived

terminal

# USDC balance of the agent wallet (mainnet)
spl-token balance EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --owner $(solana-keygen pubkey ~/.config/citable/agent.json) \
  --url https://api.mainnet-beta.solana.com

# or open it in an explorer
open "https://solscan.io/account/$(solana-keygen pubkey ~/.config/citable/agent.json)"

solana balance shows SOL, not USDC — it will say 0 and that is fine. Use the token balance above, or the explorer link.

4 · Point the agent at it

The MCP server already defaults to this file, so only the spend cap needs setting; the same file works for the x402 SDK. CITABLE_MAX_PRICE is enforced before anything is signed, so an over-priced call fails instead of paying.

env

# MCP (Claude Code / Codex / Cursor / Claude Desktop)
CITABLE_WALLET=~/.config/citable/agent.json   # the default — set it only if the file lives elsewhere
CITABLE_MAX_PRICE=0.30                        # refuse any single call above this

# x402 SDK
const bytes = Uint8Array.from(JSON.parse(readFileSync(process.env.CITABLE_WALLET!, "utf8")));
const keypair = await createKeyPairSignerFromBytes(bytes);

5 · Prove it with the cheapest call #

citable_keyword_suggest costs $0.005 and returns the settlement transaction. If that settles, everything else will.

claude · citable mcp

› expand the keyword "seo api"
  suggestions   8
  questions     8
  paid          $0.005 USDC
  transaction   66X19CLe…5PJacYX   ← settled on Solana

Keeping it safe #

Rule	Because
Small balance, top up as you go	The key file is the only thing standing between the balance and anyone who reads it. Keep the balance boring.
`chmod 600` the key file; never commit it	The MCP reads it only to sign USDC transfers to Citable. Nothing else leaves your machine — but a key in a repo is a key on the internet.
Set `CITABLE_MAX_PRICE`	A price cap the wallet enforces, not the endpoint. Today's dearest call is $0.30; set it there or lower.
One agent, one wallet	Two agents sharing a key file means two spenders you cannot tell apart on the explorer.

Not a terminal person?#

The free check needs no wallet at all — one buyer question, one domain, results in the browser. For people who never want to see a key file, the sign-in wallet — Google or email, a small top-up, the same spend cap — is Option A on the funding page; the keypair path above is what every other agent wallet uses.

Fund your agent

Option A · Sign in (no crypto needed)#

Option B · A keypair you fund yourself#