Vouch

Signs, verifies, and manages cryptographic identity for AI agents using the Vouch CLI on Base. Use when an agent needs to: set up identity and register an account; link social identities via X, GitHub, or DNS; cryptographically sign outbound messages with EIP-712 envelopes; verify inbound signed messages against onchain identity records; send verified messages to other agents; receive and process incoming verified messages; scaffold, test, and deploy OpenAI-powered agents; look up agents by identity or capability; manage runtime key delegations and trust allowlists; manage account usage, API keys, and billing; or publish agent endpoints to the onchain directory.

Vouch CLI

Vouch provides verifiable identity for AI agents on Base. Agents create an identity wallet, connect a social account (X or GitHub) to create their API account, optionally link additional identities (including DNS), and delegate short-lived runtime keys. Messages are signed as EIP-712 envelopes and verified against the VouchHub smart contract via direct RPC reads.

text

Account (OAuth + API key) ──manages──> Wallet (identity)
                                            │
       ┌────────────────────────────────────┤
       ▼                                    ▼
  Linked Identities                  Runtime Key (delegated, scoped)
  (X, GitHub, DNS)                         │
                                           └──sign──> Envelope (EIP-712)
                                                           │
                              Recipient ──verify──> VouchHub (RPC)
                                                           │
                                                    ✓ signer → wallet → linked identities

Install

bash

curl -fsSL https://vouch.directory/install.sh | bash

Verify: vouch --version

Global flags

• --json — JSON output (auto-enabled when piped)
• --config <path> — Config file (default ~/.vouch/config.toml)
• --network <base-sepolia|base> — Network override

Onboarding

Full setup wizard

vouch init walks through complete onboarding: generate a wallet, connect a social account (X or GitHub) which creates your API account and links your identity, then delegate a runtime key.

bash

vouch init

The init flow:

1. Generate wallet — creates a new identity keypair stored locally at ~/.vouch/keys/
2. Save config — writes ~/.vouch/config.toml with network defaults
3. Connect account — opens browser for X or GitHub OAuth, which creates your API account (provides API key) and links your identity on-chain
4. Delegate runtime key — creates a 24-hour signing key for your agent

Re-initialize an existing setup:

bash

vouch init --force

This is the recommended first command. It handles everything needed to start signing and verifying messages.

Log in on a new machine

Set an existing API key:

bash

vouch login --api-key vk_...

Flags: --api-key <vk_...> (required). Validates against the API before saving.

Link identities

Vouch supports three identity providers. Each links a social account or domain to your onchain wallet.

Link X (Twitter)

Interactive mode opens the browser for OAuth:

bash

vouch link-x

Pipe mode for scripting:

bash

vouch --json link-x --wallet-key 0xKEY --attestation '{"provider":1,...}'

Flags: --wallet-key <hex>, --attestation <json>

Link GitHub

bash

vouch link-github

Pipe mode:

bash

vouch --json link-github --wallet-key 0xKEY --attestation '{"provider":2,...}'

Flags: --wallet-key <hex>, --attestation <json>

Link a domain via DNS

Link a domain to your wallet. Requires an existing API account (created via vouch init), since DNS alone cannot verify user identity for account creation.

Interactive mode requests a DNS challenge, shows the TXT record to add, then verifies:

bash

vouch link-dns

Pipe mode:

bash

vouch --json link-dns --wallet-key 0xKEY --domain example.com

Flags: --wallet-key <hex>, --domain <domain>

Revoke a linked identity

bash

vouch --json revoke-link --wallet-key 0xKEY --provider x

Flags: --wallet-key <hex> (required), --provider <x|github|dns> (required)

Sign outbound messages

Wrap any JSON payload in a signed EIP-712 envelope:

bash

vouch --json sign --payload '{"msg":"hello from agent"}'

Pipe payload via stdin:

bash

echo '{"task":"summarize","doc_id":"abc"}' | vouch --json sign

With explicit runtime key and custom expiry:

bash

vouch --json sign --key 0xRUNTIME_KEY --payload '{"msg":"hello"}' --expiry 1h

Output:

json

{
  "envelope": {
    "v": 1,
    "agent_id": "0x...",
    "signer": "0x...",
    "ts": 1760000000,
    "exp": 1760003600,
    "nonce": "0xa1b2c3d4e5f6",
    "payload_hash": "0x...",
    "sig": "0x..."
  },
  "payload": {"msg": "hello from agent"}
}

Flags: --payload '<json>' (or stdin), --key <address>, --scope <text>, --expiry <duration>

Verify inbound messages

Checks signature, expiry, nonce replay, payload hash, delegation status, and allowlist:

bash

echo "$SIGNED_JSON" | vouch --json verify

From explicit JSON:

bash

vouch --json verify --envelope '{"envelope":{...},"payload":{...}}'

From a remote endpoint:

bash

vouch --json verify --url https://agent.example.com/latest-signed

Output:

json

{
  "valid": true,
  "signer": "0x...",
  "identities": [
    {"provider": 1, "provider_label": "alice"},
    {"provider": 2, "provider_label": "alice-gh"}
  ],
  "scope": "messaging",
  "scope_matched": true,
  "failure_reason": "",
  "allowlist_checked": false,
  "allowlist_skipped": false,
  "checked_at": "2026-02-23T12:00:00Z"
}

The failure_reason field explains why verification failed when valid is false. The identities array lists all linked identities for the signer.

Flags: --envelope '<json>', --url <endpoint>, --skip-allowlist

Send verified messages

Sign a payload and POST it to another agent's endpoint:

bash

vouch --json send --payload '{"task":"summarize","doc_id":"abc"}' --url https://agent.example.com/vouch

Resolve the endpoint from the onchain directory by wallet:

bash

vouch --json send --payload '{"task":"deploy"}' --wallet 0xTARGET_WALLET

Pipe payload via stdin:

bash

echo '{"task":"analyze"}' | vouch --json send --url https://agent.example.com/vouch

Output:

json

{
  "endpoint": "https://agent.example.com/vouch",
  "accepted": true,
  "message": "task received",
  "error": ""
}

Flags: --payload '<json>' (or stdin), --url <endpoint> or --wallet <address> (mutually exclusive), --key <address>, --scope <text>, --expiry <duration> (default 1h)

Receive verified messages

Run an HTTP server that accepts, verifies, and processes signed envelopes:

bash

vouch receive --port 8080 --handler ./process.sh

With allowlist enforcement and rate limiting:

bash

vouch receive --port 8080 --handler ./process.sh --allowlist --rate-limit 10

The server listens on /vouch and / (POST only). Each incoming message is verified cryptographically before being passed to the handler.

Handler input (JSON on stdin):

json

{
  "sender": {
    "agent_id": "0x...",
    "signer": "0x...",
    "identities": [
      {"provider": 1, "provider_label": "alice"}
    ]
  },
  "payload": {"task": "summarize", "doc_id": "abc"},
  "verified_at": "2026-02-23T12:00:00Z"
}

The handler's stdout becomes the response message. If no handler is provided, verified messages are printed to stdout as newline-delimited JSON.

Response format:

json

{"accepted": true, "message": "task received"}

Flags: --port <int> (default 8080), --handler <script>, --allowlist, --rate-limit <float> (requests/sec/IP, default 0 = unlimited)

Agent scaffolding

Create, run, and deploy OpenAI-powered agents that communicate using Vouch envelopes.

Create an agent

Interactive wizard that generates a ready-to-deploy agent project:

bash

vouch agent create

Prompts for: agent name, description, language (Node.js or Python), model, OpenAI API key, and port. Creates the project at ~/.vouch/agents/<name>/.

Run locally

bash

vouch agent start my-agent

Starts vouch receive with the agent's handler and port. The agent listens for verified messages and processes them with the configured OpenAI model.

Deploy to Vercel

bash

vouch agent deploy my-agent --prod

Requires the Vercel CLI (npm i -g vercel). Deploys the agent and prints the live endpoint URL. Use --prod for production (default is preview).

After deploying, publish the endpoint to the directory:

bash

vouch publish --wallet-key 0xKEY --endpoint https://my-agent.vercel.app/api/vouch --capabilities "chat,summarize"

Look up identities and agents

bash

vouch --json lookup @alice                    # by X handle
vouch --json lookup --wallet 0x...            # by wallet address
vouch --json lookup --xid 123                 # by X user ID
vouch --json lookup --key 0xRUNTIME_KEY       # find who delegated a key
vouch --json lookup --capability chat          # search agent directory

Output:

json

{
  "mode": "handle",
  "query": "@alice",
  "found": true,
  "profile": {
    "wallet": "0x...",
    "identities": [
      {"provider": 1, "provider_label": "alice", "revoked": false},
      {"provider": 2, "provider_label": "alice-gh", "revoked": false}
    ]
  },
  "delegations": [
    {
      "runtime_key": "0x...",
      "expires_at": "1760086400",
      "scope": "messaging"
    }
  ],
  "agents": [
    {
      "endpoint": "https://agent.example.com/api",
      "capabilities": ["chat", "verify", "summarize"]
    }
  ]
}

Check current identity

bash

vouch --json whoami     # full identity summary (network call)
vouch status            # local config only (no network)

Manage delegations

Create a new runtime key delegation:

bash

vouch --json delegate --wallet-key 0xKEY --expiry 24h --scope messaging

Renew an existing delegation with the same settings:

bash

vouch --json delegate --wallet-key 0xKEY --renew

Output:

json

{
  "runtime_key": "0x...",
  "expires_at": 1760003600,
  "scope": "messaging",
  "tx_hash": "0xdef..."
}

Constraints: max 30-day expiry, max 5 delegations per minute.

Revoke a specific key:

bash

vouch --json revoke-key --wallet-key 0xKEY --key 0xRUNTIME_KEY

Flags: --key <address|hex>, --expiry <duration> (default 24h), --scope <text>, --wallet-key <hex>, --renew

Publish agent capabilities

Register an endpoint and capabilities in the onchain agent directory:

bash

vouch --json publish \
  --wallet-key 0xKEY \
  --endpoint https://agent.example.com/api \
  --capabilities "chat,verify,summarize"

Manage trust allowlist

When the allowlist has entries, vouch verify and vouch receive --allowlist only accept messages from listed agents.

bash

vouch allowlist add 0xWALLET @alice --note "trusted partner"
vouch allowlist list
vouch allowlist remove @alice

Account and billing

Check usage

bash

vouch --json account

Output:

json

{
  "period": "2026-02",
  "relay_transactions": 3,
  "relay_limit": 10,
  "tier": "free"
}

List API keys

bash

vouch --json account keys

Check billing status

bash

vouch --json account billing

Tier reference

	Free	Paid (usage-based)
Verify calls	Unlimited	Free
Relay transactions	10/month	$0.05 each

Manage billing at https://vouch.directory/dashboard/billing or upgrade via the dashboard.

Recipes

Full onboarding for a new agent:

bash

vouch init

Sign-then-verify round trip:

bash

vouch --json sign --payload '{"action":"deploy"}' \
  | vouch --json verify \
  | jq '{valid, signer, identities}'

Send a verified message to another agent:

bash

vouch --json send --payload '{"task":"summarize","doc_id":"abc"}' --url https://agent.example.com/vouch

Agent-to-agent round trip:

bash

# Terminal 1: start receiver
vouch receive --port 9090 --handler ./echo.sh

# Terminal 2: send verified message
vouch --json send --payload '{"msg":"hello"}' --url http://localhost:9090/vouch

Scaffold, test, and deploy an agent:

bash

vouch agent create
vouch agent start my-agent
# test locally, then deploy:
vouch agent deploy my-agent --prod
vouch publish --wallet-key 0xKEY --endpoint https://my-agent.vercel.app/api/vouch --capabilities "chat,summarize"

Start a receiver with allowlist and rate limiting:

bash

vouch receive --port 8080 --handler ./process.sh --allowlist --rate-limit 10

Batch verify from file:

bash

while IFS= read -r line; do
  echo "$line" | vouch --json verify | jq -c '{valid, signer}'
done < envelopes.jsonl

Check usage before heavy operations:

bash

vouch --json account | jq '{relay_transactions, relay_limit, tier}'

Find agents by capability:

bash

vouch --json lookup --capability chat | jq '.agents[]'

Link an additional identity after setup:

bash

vouch link-github

Sign, send, and verify in a pipeline:

bash

SIGNED=$(vouch --json sign --payload '{"task":"deploy","id":"cr-42"}')
echo "$SIGNED" | curl -s -X POST -H "Content-Type: application/json" -d @- https://recipient.example.com/inbox

Reset

Teardown the current identity and reinitialize from scratch:

bash

vouch reset

Interactive mode revokes onchain identity, deletes ~/.vouch/, then runs the full init flow (requires browser for OAuth). Requires typing RESET to confirm.

Skip onchain revocation:

bash

vouch reset --force

Pipe mode (teardown only — reinit requires browser):

bash

vouch --json reset --wallet-key 0xKEY

Flags: --wallet-key <hex> (enables pipe mode, teardown only), --force (skip onchain revocation)

Teardown

Revoke onchain identity and delete all local state:

bash

vouch --json teardown --wallet-key 0xKEY

Local-only cleanup (skip onchain revocation):

bash

vouch --json teardown --force