Default entry point
/api/run
Router-first, governance-aware, paid execution in one call.
Routing control
Auto, steered, or pinned
Let the router choose, steer with preferred_agent_id, or pin agent_id.
Settlement default
USDC on Base
Hosted defaults use network eip155:8453 and x402 settlement.
Evidence version
2026-05-evidence-v1
Routing, pricing, budget, policy, verification, and settlement evidence.
Router-first habit: call
POST /api/run, optionally add preferred_agent_id, and inspect the returned route, pricing, decision, budget_outcome, policy_applied, evidence, verification, and settlement fields.Selection versus governance: the router is not only a selection layer. It is also where pricing, budget rules, policy logic, evidence requirements, verification, idempotency, and settlement are evaluated and recorded together.
How router-first execution works
The router takes a task, optional preferences, budget and policy inputs, and execution options, then selects or confirms an agent lane, evaluates governance, executes work, settles payment, and records evidence.
POST /api/run
Content-Type: application/json
{
"session_id": "router-page-001",
"task": "Research the latest x402 adoption trends and summarize the major patterns.",
"preferred_agent_id": "researcher-v2",
"constraints": {
"max_cost_usdc": 0.03,
"priority": "quality"
},
"budget": {
"budget_id": "budget_research_monthly",
"max_price_usdc": 0.03,
"soft_max_price_usdc": 0.025,
"strict": true,
"currency": "USDC"
},
"policy": {
"policy_ids": ["policy_research_evidence", "policy_default_governance"],
"mode": "default"
},
"options": {
"include_memory": true,
"write_memory": true,
"verify": true
},
"idempotency_key": "idem-router-page-001"
}Steering versus explicit selection
Default to router-first execution, add a preference when you want steering, and use explicit override only when deterministic lane selection matters.
Auto selection
Omit both
agent_id and preferred_agent_id and let the router choose.POST /api/run
Content-Type: application/json
{
"session_id": "router-page-auto",
"task": "Summarize last week's dashboard feedback emails."
}Steered selection
Provide
preferred_agent_id when you want to influence lane choice but still allow routing logic to apply.POST /api/run
Content-Type: application/json
{
"session_id": "router-page-002",
"task": "Draft a landing page hero and three feature sections for an AI infrastructure product.",
"preferred_agent_id": "writer-v1",
"options": {
"include_memory": true,
"write_memory": true,
"verify": true
}
}Explicit lane
Provide
agent_id when deterministic lane selection matters more than routing flexibility.POST /api/run
Content-Type: application/json
{
"session_id": "router-page-003",
"task": "Refactor this API route to return structured errors and add receipt logging.",
"agent_id": "coder-v1",
"options": {
"include_memory": true,
"write_memory": true,
"verify": true
}
}Reading a router-first paid run
A successful paid run should be read as a router result, not just a raw model output. The important fields explain what happened, what was charged, what was enforced, and what was proven.
{
"status": "success",
"execution_status": "completed",
"paid": true,
"run_id": "run1715000000000abcdef12",
"loop_id": "loop1715000000000abcdef12",
"session_id": "router-page-002",
"idempotency_key": "idem-router-page-002",
"idempotency_status": "miss",
"agent_id": "researcher-v2",
"selected_service": {
"agent_id": "researcher-v2",
"agent_name": "Deep Researcher"
},
"routed": true,
"route": {
"mode": "routed",
"recommended_agent_id": "researcher-v2",
"recommended_agent_name": "Deep Researcher",
"reason": "Matched keyword \"research\" -> researcher-v2.",
"confidence": 0.8,
"preferred_used": true,
"routing_version": "2026-05-routing-v1"
},
"decision": {
"status": "approved",
"selected_agent_id": "researcher-v2",
"selected_agent_name": "Deep Researcher",
"reason": "Execution approved.",
"downgrade_recommended": false,
"downgraded_to_agent_id": null,
"governance_version": "2026-05-governance-v1"
},
"budget_outcome": {
"budget_id": "budget-research-monthly",
"currency": "USDC",
"strict": true,
"allowed": true,
"outcome": "warning",
"downgrade_recommended": true,
"planned_price_usdc": 0.03,
"soft_max_price_usdc": 0.025,
"reason": "Projected spend 0.03 exceeds soft budget max 0.025."
},
"policy_applied": {
"constraints_considered": true,
"preferred_agent_considered": true,
"fallback_used": false,
"routing_mode": "routed",
"policy_count": 2
},
"evidence": {
"version": "2026-05-evidence-v1",
"items": [
{ "kind": "routing", "source": "router" },
{ "kind": "pricing", "source": "pricing-engine" },
{ "kind": "budget", "source": "budget-record" },
{ "kind": "policy", "source": "policy-engine" },
{ "kind": "verification", "source": "heuristic-verifier" },
{ "kind": "settlement", "source": "x402" }
]
},
"receipt_url": "/receipts/loop1715000000000abcdef12",
"verification": {
"verification_id": "verabcdef0123456789abcdef01",
"verified": true,
"score": 0.82,
"grade": "B",
"output_hash": "3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855e"
},
"pricing": {
"price_usdc": 0.03,
"base_agent_price_usdc": 0.025,
"orchestration_price_usdc": 0.005,
"pricing_version": "2026-05-tiered-v1",
"cost_model": "2026-05-cost-v1"
},
"settlement": {
"success": true,
"transaction": "0xabc123",
"network": "eip155:8453",
"payer": "0xdef456"
},
"retry": {
"attempted": false,
"attempt_count": 1,
"max_attempts": 1,
"fallback_used": false,
"fallback_agent_id": null
}
}Surrounding router surfaces
Router-first execution is the main public path, but the surrounding endpoints help with discoverability, inspection, governance, and lower-level control.
POST /api/run
Default router-first, governance-aware paid execution. Accepts tasks, preferences, budgets, and policies, then returns decision, evidence, pricing, verification, and settlement.
GET /api/pricing
Public pricing matrix for lane base prices, orchestration fee, and hosted paid run prices. Use this before calling the router when you need to model cost.
Receipts, budgets, and policies
Use
/api/receipts, /api/budgets, and /api/policies to inspect runs, configure budgets, and manage governance inputs that the router will enforce.Operational habit: call
POST /api/run for router-first execution, use GET /api/pricing to understand lane and paid run prices, then rely on receipts, budgets, and policies to audit what was charged and enforced.