pai

pai runs on your machine and manages a Phantom AI key. Your agent can hand each subagent a child key with its own spending limit, lifetime, and rate cap. It also sets plans and model routing, pays for credit from an agent wallet, and checks which model answered a call.

pi, Claude Code, Codex, and Cursor drive it through a skill, and any MCP client can use pai mcp.

The CLI is MIT licensed. The Phantom AI API it calls is a hosted service.

How It Works

                       ┌────────────────────────┐
                       │    Main Phantom Key    │
                       │   (prepaid, no id)     │
                       └───────────┬────────────┘
                                   │
           ┌───────────────────────┼───────────────────────┐
           │ pai child             │ pai child             │ pai wallet
           ▼                       ▼                       ▼
    ┌──────────────┐        ┌──────────────┐        ┌──────────────┐
    │  Researcher  │        │  Code Agent  │        │ Agent Wallet │
    │  Claude Code │        │    Cursor    │        │  (Solana)    │
    │  $0.50 limit │        │  $1.00 limit │        │  auto-topup  │
    │  6 hour TTL  │        │  $0.10 / min │        │  below $1.00 │
    └──────┬───────┘        └──────┬───────┘        └──────────────┘
           │                       │
           └───────────┬───────────┘
                       ▼
           ┌───────────────────────┐
           │   Phantom AI Gateway  │  ──> https://phantom.codes/v1
           │   (zero prompt logs)  │  ──> Ed25519 signed receipts
           └───────────────────────┘

Related MCP server: L402 Gateway

Features

• Scoped Subagent Keys — Create child keys that spend the parent's balance up to a limit, with lifetimes and rate caps (pai child). Revoke one with pai burn.

• Autonomous Agent Wallet — Local Solana keypairs allow running agents to self-fund inference on chain. Capped by environment-only limits (PHANTOM_WALLET_MAX_USD).

• Multi-Agent Skill & MCP — Native skill installation for pi, Claude Code, Codex, and Cursor, plus a 16-tool Model Context Protocol (MCP) server over stdio.

• Cryptographic Receipts — Upstream responses return an Ed25519 signature verifying the model served, actual token counts, and cost (pai verify).

• Local Tooling Suite — Private local markdown memory notebooks, throwaway Docker sandboxes, and safe IMAP/SMTP mail drafting.

Install

npm i -g @phantom-ai/pai

The package also installs the same CLI as phantom-key, its earlier name.

Quickstart

# 1. Login once and install the skill for your installed agents
pai login          # paste your key once; pai saves it with mode 600
pai setup          # configures pi, Claude Code, Codex, and Cursor

# 2. Check balance and active caps
pai balance

# 3. Mint a child key for an autonomous subagent
pai child --limit 0.50 --ttl 6 --rate 0.10 --save researcher

# 4. Run the subagent as the scoped child
PHANTOM_KEY_NAME=researcher claude

Use It From an Agent

pai setup installs the phantom-ai skill for each agent it finds in your home directory (pi, Claude Code, Codex, Cursor). You can then prompt your agent in plain words, for example:

"Give a subagent $0.50 for 6 hours with a $0.10/min rate cap."

• --agent pi (or claude, codex, cursor) sets up one agent.

• --mcp also registers the MCP server with Claude Code, Codex, and Cursor.

• pi has no MCP and uses the CLI through the skill; install there with:

  pi install npm:@phantom-ai/pai

Commands

pai --help prints every command and flag. docs/reference.md has the complete text, the MCP tools, and the environment variables, all generated from the code.

A command runs as the saved key named by PHANTOM_KEY_NAME if it is set, then as PHANTOM_API_KEY, then as the login key. A subagent started with PHANTOM_KEY_NAME=<child> runs as the child even when your parent key is exported.

Memory

Each agent gets a private notebook on this machine. Notes are markdown files in ~/.config/phantom-key/memory/<space>/, so you can read, edit, or commit them. pai sends none of them anywhere.

pai picks the notebook from --space, then PAI_MEMORY_SPACE, then the saved key name (PHANTOM_KEY_NAME), then main, so each subagent keeps its own.

Mail

pai reads your own mailbox over IMAP and SMTP. It saves the login, with an app password, in ~/.config/phantom-key/mail.json (mode 600). Gmail, Outlook, iCloud, and Fastmail addresses have presets; for any other provider, pass --imap host:port --smtp host:port.

Browser and Sandbox

pai wraps two existing tools:

Output Format

Commands print JSON on stdout, so you can pipe into jq. --table prints a formatted table for human inspection. browser and sandbox run pass through the exit code of the command they ran.

Use With an MCP Client

pai mcp starts an MCP server over stdio. Add it to your client's config:

{
  "mcpServers": {
    "phantom": {
      "command": "npx",
      "args": ["-y", "@phantom-ai/pai", "mcp"]
    }
  }
}

docs/reference.md lists every tool with its inputs and whether it is read-only or destructive.

delete_key authenticates as the key you pass in api_key or key_name and deletes that key. It refuses the key the server runs as; use pai burn for that.

Let the Agent Pay

The agent can maintain its own Solana wallets and buy credit with them. Each wallet is a Solana keypair in ~/.config/phantom-key/wallets/ (mode 600). The wallet pays Phantom AI's Solana address, and Phantom AI finds the payment on chain.

1. Create a wallet, and back up its file:

   pai wallet create --table              # saved as "main"
   pai wallet create --name work --table  # a second one

2. Fund the address with USDC on Solana, plus some SOL for fees (at least 0.003 SOL).

3. Set the safety cap:

   export PHANTOM_WALLET_MAX_USD=10

   Without this variable, pai refuses to pay. The total over 24 hours is capped by PHANTOM_WALLET_MAX_USD_PER_DAY, which defaults to the same amount: one payment a day. Raise it for autotopup.

4. Pay:

   pai buy --amount 5 --pay

   With more than one wallet saved, pai asks in a terminal which one pays. It then reports each step:

   1. Getting a payment request from Phantom AI (amount, recipient, and unique reference)

   2. Sending USDC or SOL from your wallet

   3. Confirming on Solana

   4. Phantom AI finding the payment on chain by its reference

   5. Credit balance before and after

   A payment request expires after 30 minutes.

You can also prompt your agent: "Top up my Phantom AI key with $5 from my Phantom agent wallet." Over MCP it calls list_wallets, asks which wallet if not specified, then calls pay_for_credit.

To refill automatically when the balance runs low:

pai autotopup --below 1 --amount 5 --wallet main --every 10

Safeguards

• pai pays the recipient and exact amount the payment request names, with that request's reference attached.

• pai reads PHANTOM_WALLET_MAX_USD and PHANTOM_WALLET_MAX_USD_PER_DAY strictly from the environment; no flag or tool argument can raise them.

• Before signing, pai checks the payment request against what it asked for: the coin, the USDC mint, and an amount no more than requested (for SOL, within 10% of Coinbase's price). A wrong or hostile PHANTOM_BASE_URL cannot make it sign more.

• One payment runs at a time, across processes.

• pai verifies the wallet balance before requesting a payment.

• pai records payments in ~/.config/phantom-key before sending, and keeps the record until Phantom AI reports the payment credited or dead. If a run crashes, times out or loses the connection, the next run waits for that payment instead of paying again.

• These limits bind an agent that reaches pai through MCP. An agent with its own shell can set environment variables and edit the state folder, so give such an agent a wallet holding only what you are willing for it to spend.

• Store wallet secrets in a local secrets manager (e.g. KRU) and inject PHANTOM_WALLET_KEY at runtime.

Configuration

pai reads its settings from environment variables. Run pai --help or see docs/reference.md#environment-variables for the full list, including secrets, environment-only flags, and caps.

Requirements

• Node 24 or newer

• Runtime dependencies: @modelcontextprotocol/sdk and zod for mcp, @solana/kit for wallet payments, and imapflow, mailparser, nodemailer for mail.

Read phantom.codes/docs/concepts for key lifecycle and subagent hierarchy details.

Development

npm ci
npm test                # vitest
npm run typecheck
npm run docs            # regenerate docs/reference.md
node src/pai.mts --help # run from source

Contributing

See CONTRIBUTING.md for setup, style, and how to add a command or MCP tool. CHANGELOG.md lists changes by release.

Security

Report vulnerabilities privately through a GitHub security advisory. See SECURITY.md.

License

MIT