>_ DOCS / HOW-TO GUIDES / AGENT INTEGRATION
YOUR AGENT.
OUR INFRASTRUCTURE.
Connect P402 to OpenClaw, Hermes Agent, or any OpenAI-compatible agent framework. Budget caps, semantic caching, and 300+ model routing with zero code changes.
>_ OPENCLAW
24/7 AGENT WITH BUDGET CONTROLS.
OpenClaw is an open-source personal AI agent (MIT, 200K+ GitHub stars) that runs as a persistent daemon and connects to WhatsApp, Telegram, Slack, Discord, and 20+ messaging platforms. It is model-agnostic and accepts any OpenAI-compatible provider. P402 plugs in as a base URL swap.
{
"providers": {
"p402": {
"type": "openai",
"baseURL": "https://p402.io/api/v2",
"apiKey": "${P402_API_KEY}"
}
}
}What you get
- +Automatic model selection (cost / quality / speed / balanced)
- +Semantic cache: identical queries return at zero cost in <50ms
- +Billing guard: 6-layer spending protection
- +300+ models via OpenRouter, no per-provider config
Recommended mode
Most OpenClaw agents should use cost mode. Autonomous agents burn tokens on heartbeats, tool calls, and sub-agent tasks. Cost mode selects the cheapest capable model per request.
MCP Tools
| Tool | Purpose |
|---|---|
| p402_chat | Route a message through the AI router |
| p402_create_session | Create a budget-capped session |
| p402_get_session | Check remaining budget |
| p402_list_models | Browse models and pricing |
| p402_compare_providers | Compare provider costs |
| p402_health | Check router health |
SOUL.md Addition
Add this to your agent's SOUL.md for autonomous budget management:
## Budget Management Before any task that may consume significant tokens (code generation, research, long-form writing), check your P402 session balance using the p402_get_session tool. If remaining budget is below $1.00, notify the user and suggest funding the session. Default to cost routing mode for routine tasks.
>_ HERMES AGENT
SELF-IMPROVING AGENT, CONTROLLED SPEND.
Hermes Agent (by Nous Research, 61K+ GitHub stars) is a Python-based autonomous agent with a built-in learning loop, skill system, and support for 6 terminal backends. It configures providers in ~/.hermes/config.yaml and supports any OpenAI-compatible endpoint via custom providers.
# Interactive setup
hermes model
# Choose "Custom endpoint"
# Base URL: https://p402.io/api/v2
# API Key: your P402 API key
# Model: auto
# Or edit ~/.hermes/config.yaml directly:
model:
provider: "custom"
default: "auto"
custom_providers:
p402:
base_url: "https://p402.io/api/v2"
api_key: "${P402_API_KEY}"
# Set in .env
hermes config set P402_API_KEY your-key-hereFallback chain
Hermes supports provider fallback. Use P402 as primary with a direct provider as backup:
fallback_model: provider: "openrouter" model: "anthropic/claude-sonnet-4-6"
Migration note
If you are migrating from OpenClaw to Hermes, run hermes claw migrate first. Your P402 provider config will carry over automatically if it was stored in OpenClaw's config.
MCP Tools
| Tool | Purpose |
|---|---|
| p402_chat | Route a message through the AI router |
| p402_create_session | Create a budget-capped session |
| p402_get_session | Check remaining budget |
| p402_list_models | Browse models and pricing |
| p402_compare_providers | Compare provider costs |
| p402_health | Check router health |
>_ UNIVERSAL INTEGRATION
TWO VALUES. ANY FRAMEWORK.
P402 is an OpenAI-compatible API. Change baseURL and apiKey. That is the entire integration. The p402 options block (routing mode, caching, session binding) is optional -- P402 defaults to balanced mode with caching enabled.
from openai import OpenAI
client = OpenAI(
base_url="https://p402.io/api/v2",
api_key=os.environ["P402_API_KEY"],
)
response = client.chat.completions.create(
model="auto",
messages=[{"role": "user", "content": "Explain blockchain in one sentence."}],
extra_body={
"p402": {
"mode": "cost",
"cache": True,
"session_id": "sess_xxx",
}
},
)
print(response.choices[0].message.content)Budget Sizing Guide
| Agent Type | Starting Budget | Routing Mode |
|---|---|---|
| Heartbeat / monitoring | $1 - $5 | cost |
| Research / browsing | $5 - $20 | balanced |
| Coding agent | $10 - $50 | balanced or quality |
| Multi-agent orchestrator | $20 - $100 | balanced |
>_ ENVIRONMENT
SECRETS AND HOSTING.
# In your Zo Computer app settings
# Add environment variable:
P402_API_KEY=your-key-here
# Or via the Zo CLI:
zo env set P402_API_KEY your-key-here
# Verify
zo env list | grep P402Verification
curl -s https://p402.io/api/v2/health \ -H "Authorization: Bearer $P402_API_KEY" | jq .
Multi-agent note
A single P402 API key serves multiple agents. Use separate session_id values per agent to track spend independently.
>_ SESSION LIFECYCLE
CREATE. FUND. USE. MONITOR.
curl -X POST https://p402.io/api/v2/sessions \
-H "Authorization: Bearer $P402_API_KEY" \
-H "Content-Type: application/json" \
-d '{"budget_usd": 5}'Pay USDC on Base
→ POST /api/v2/sessions/fund
{
"session_id": "sess_xxx",
"amount": 5,
"tx_hash": "0x..."
}{
"messages": [...],
"p402": {
"session_id": "sess_xxx",
"mode": "cost",
"cache": true
}
}curl https://p402.io/api/v2/sessions/{id}/stats \
-H "Authorization: Bearer $P402_API_KEY"