Vault

Self-custodial execution wallet for AI agents on Robinhood Chain. Authorize x402 payments and trade ERC-20s and RWAs without exposing private keys.

What is Vault?

Vault is a desktop application that manages on-chain authorization for AI agents. When your agents need to pay for x402 services or execute token swaps on Uniswap, they request authorization from Vault. You approve or deny, and Vault signs transactions using your wallet — your keys never leave the device.

Two authorization lanes:

• DeFi Trading — agents submit swap requests for ERC-20 tokens and RWAs; Vault re-quotes independently via Uniswap v3/v4, enforces trading limits, and executes on-chain.
• x402 Payments — agents request signatures for paywalled APIs; Vault enforces spending policies and signs EIP-712 TransferWithAuthorization messages. Contains the full MultiClaw engine for x402 v1/v2 protocol support.

Both lanes share the same agent identity, policy system, and approval workflow. The agent never sees private keys.

Key Features

Supported Network

Vault is built for Robinhood Chain (chain ID 4663), an L2 with native USDG (Global Dollar) stablecoin and RWA (Real World Asset) token support.

All x402 payments use USDG. Trading supports any ERC-20 or RWA token with Uniswap liquidity on RHC.

Interfaces

Vault provides four ways to interact:

CLI and Console share the same command set. See Commands Reference for details.

Installation

Option A — pip (recommended)

# CLI and headless only
pip install primer-vault

# Full GUI included
pip install primer-vault[gui]

Then run primer-vault from any terminal.

Option B — Standalone executable

Download the latest Vault.exe from GitHub Releases. Double-click to launch GUI mode, or run from a terminal for CLI access. No installation required — can be run locally or from USB.

Getting Started

Vault is best experienced via its clean, intuitive GUI on your desktop; most users will find this the easiest way to get started. You can also approach it by CLI:

1. Create a Wallet

On first launch, create a new wallet or import an existing seed phrase. The wallet is encrypted with AES-256-GCM using Argon2id key derivation.

# CLI mode
wallet create mywallet
seed create
address create S001 0 "Agent Funding"

2. Fund Your Wallet

Send ETH (for gas) and USDG to your wallet address. The app shows your balance via Blockscout API with auto-discovery of all tokens including RWAs.

3. Create a Spend Policy

Define spending rules for x402 payments:

# CLI mode - x402 payment policy
policy create standard --day 100 --txn 10 --auto 1

• Daily limit (--day) — maximum total spending per day (USDG)
• Per-request max (--txn) — maximum single payment amount
• Auto-approve threshold (--auto) — payments below this are signed automatically
• Domain restrictions — allowlist or blocklist specific domains

To enable trading, add trading options:

# Policy with trading enabled
policy create trader --day 100 --txn 10 --auto 1 \
  --trading --trade-daily 500 --trade-max 100 --trade-auto 25

• Enable trading (--trading) — allow this policy to execute swaps
• Daily volume (--trade-daily) — max notional USD per day (default: 500)
• Per-trade max (--trade-max) — single trade size limit (default: 100)
• Trade auto-approve (--trade-auto) — auto-execute trades below this

4. Register an Agent

agent register "My Claude Agent" --auth hmac

• HMAC (recommended) — agent signs requests with a shared secret
• Bearer — agent sends a static token (simpler, less secure)

Copy the agent credentials to your AI agent's environment. Lost the credentials? Use agent instructions <name> or click "View Instructions" in the agent properties dialog.

5. Commission the Agent

Assign a wallet and spend policy to the agent:

agent commission XK7M2P standard A001

6. Start the Server

# CLI mode
server start

# GUI mode - click "Start Server" in Network tab

The agent server listens on localhost:4663 by default.

Note: The agent server requires a long-running process. In GUI mode, the server runs while the application is open. For CLI usage, use interactive mode (primer-vault --cli) or headless mode (primer-vault --headless) to keep the server running. One-shot commands like primer-vault server start will exit immediately after execution.

Agent Integration

Agents communicate with Vault via HTTP on localhost:4663.

x402 Payment Flow

1. Agent receives HTTP 402 with Payment-Required header
2. Agent forwards the header to POST /sign
3. Vault validates against policy, signs if allowed
4. Agent receives signed payment header
5. Agent retries original request with PAYMENT-SIGNATURE header

Trading Flow

1. Agent posts trade request to POST /trade
2. Vault re-quotes via Uniswap Quoter contract
3. Vault validates against trading policy
4. Trade executes on-chain (or escalates for approval)
5. Agent receives tx_hash and execution result

Example: Payment Request (Bearer Mode)

POST http://localhost:4663/sign
Content-Type: application/json

{
  "agent_code": "ABC123",
  "signature": "AT_your_token_here",
  "payment_required": "eyJhY2NlcHRzIjpbey4uLn1d",
  "request_url": "https://api.example.com/resource"
}

Example: Trade Request

POST http://localhost:4663/trade
Content-Type: application/json

{
  "agent_code": "ABC123",
  "signature": "AT_your_token_here",
  "token_in": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
  "token_out": "0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73",
  "amount_in": "100.0",
  "fee_tier": 3000,
  "max_slippage_bps": 50
}

Manual Approval

When a payment or trade exceeds the auto-approve threshold, Vault returns status: pending with a request_id. A dialog appears for you to approve or deny. The agent polls the status endpoint until resolved.

API Endpoints

Agent server runs on port 4663 (configurable). Admin API runs on port 4664 (localhost only).

Agent Endpoints (port 4663)

Trading

Vault executes trades via Uniswap v3 and v4 on Robinhood Chain.

Supported Operations

• Token → Token swaps via Uniswap pools
• ETH → WETH wrapping (no pool needed)
• WETH → ETH unwrapping (no pool needed)

Uniswap v3 Fee Tiers

V4 Differences

Uniswap v4 uses a singleton PoolManager architecture. V4 trades require additional fields:

• tick_spacing — pool tick spacing (required)
• hooks — hooks contract address (use zero address for no hooks)

Version is inferred from field presence or can be explicitly set via dex_version: "v4".

Note: RHC's UniversalRouter has a modified interface with an extra minHopPriceX36 field. Standard Uniswap SDK calldata will revert — use Vault for all trades.

Spend Policies

Policies define what an agent can spend and trade. Each agent is assigned exactly one policy.

x402 Payment Limits

• Daily limit — maximum spending per calendar day (UTC). Agent status changes to "limit_reached" when exhausted.
• Per-request max — requests exceeding this are rejected outright.
• Auto-approve threshold — payments below this are signed without prompting. Set to 0 for manual-only.
• Allowed domains — if set, only these domains can receive payments (includes subdomains)
• Blocked domains — these domains are always rejected (includes subdomains)

Trading Limits

• Daily trading volume — maximum notional USD value of trades per day
• Per-trade max — single trade size limit
• Auto-approve threshold — trades below this are approved without prompting. Set to 0 for manual-only.
• Minimum ETH reserve — trading stops if your ETH falls below this level
• Maximum slippage — percentage difference to tolerate between value in and value out

Authentication Modes

HMAC Mode (Recommended)

Agent signs each request with HMAC-SHA256 using a shared secret. The signature includes a timestamp for replay protection (5-minute window by default).

signature: "SIG:1707823845:abc123def456..."

More secure — the shared secret is never transmitted.

Bearer Mode

Agent sends a static token with each request.

signature: "AT_abc123def456..."

Simpler for agents that can't do cryptographic signing. Use idempotency_key to make multiple payments to the same endpoint.

Security

Wallet Encryption

Wallets are encrypted with AES-256-GCM. Key derivation uses Argon2id (64MB memory, 3 iterations, 4 threads). Each wallet has a unique salt and IV.

Agent Secrets

HMAC shared secrets are encrypted with your wallet password and can be retrieved later via agent instructions. Bearer tokens are stored as SHA-256 hashes — if lost, use --regenerate to create a new token.

Key Isolation

Agents never receive private keys. They receive a code and token that authorize them to request signatures. All signing happens locally in Vault.

Single Instance

Only one Vault instance runs per data directory. A second launch (CLI or GUI) automatically connects to the running instance.

Rate Limiting

The server limits requests to 300/minute per IP (configurable).

Admin API Protection

The admin API (port 4664) accepts connections from localhost only. Defaults as restricted to GUI-only mode to block other processes' access; power users may enable it in GUI.

Intent Mandates (AP2)

An Intent Mandate is a signed credential documenting your authorization of an agent's x402 spending. You can:

• Generate when commissioning an agent
• Publish to the AP2 Registry for merchant verification
• Share the mandate ID with merchants who want to verify authorization

The mandate includes:

• Agent code and auth fingerprint
• Spending limits (daily, per-request, auto-approve)
• Allowed networks
• Wallet address
• Your cryptographic signature

Privacy-sensitive fields (agent name, policy name, domain restrictions) are intentionally omitted from the public mandate.

Data Storage

Vault stores data in platform-standard locations:

Contents:

• wallets/ — Encrypted wallet files
• settings.json — Application settings
• logs/ — Application logs

Environment Variables

Agents receive these credentials at registration:

PRIMER_VAULT_AGENT_ID=XK7M2P
PRIMER_VAULT_AGENT_TOKEN=AT_...
PRIMER_VAULT_AUTH_MODE=hmac
PRIMER_VAULT_URL=http://localhost:4663

Comparison with MultiClaw

Vault and MultiClaw serve similar purposes but target different use cases:

Vault contains the full MultiClaw engine internally for x402 payment processing. The diagram below lays out MultiClaw's x402 interactions; see its full documentation for more information.