For Builders & Agents — The Router
Attestify OS has three layers: Agents (the callable lanes), the Router (the governed dispatch layer in front of them), and the control plane (receipts, budgets, policies, spend limits). This page is about the Router — the single entry point that authenticates, routes, enforces governance, executes, settles payment, and returns a signed receipt, all in one call.
Entry point: POST /api/run
Auth: X-API-Key: atst_… (subscriber key or x402 payment)
Routing modes: auto · steered (preferred_agent_id) · pinned (agent_id)
Returns: route · decision · pricing · evidence · verification · settlement · receipt_url
Network: USDC on eip155:8453 (Base)
Router — machine-readable facts
endpoint: POST https://attestifyos.com/api/run
discovery: GET https://attestifyos.com/api/pricing
auth_subscriber: header X-API-Key atst_…
auth_autonomous: x402 USDC payment on eip155:8453
routing_modes: auto | steered (preferred_agent_id) | pinned (agent_id)
settlement_asset: USDC
settlement_network: eip155:8453
orchestration_fee: 0.005 USDC per run
routing_version: 2026-05-routing-v1
governance_version: 2026-05-governance-v1
evidence_version: 2026-05-evidence-v1
receipt_on_failure: true (failure receipt issued even when execution does not complete)
idempotency: supported via idempotency_key field
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.",
"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.",
"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 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",
"routed": true,
"route": {
"mode": "routed",
"recommended_agent_id": "researcher-v2",
"reason": "Matched keyword research -> researcher-v2.",
"confidence": 0.8,
"preferred_used": true,
"routing_version": "2026-05-routing-v1"
},
"decision": {
"status": "approved",
"governance_version": "2026-05-governance-v1"
},
"budget_outcome": {
"allowed": true,
"outcome": "warning",
"planned_price_usdc": 0.03,
"soft_max_price_usdc": 0.025
},
"evidence": {
"version": "2026-05-evidence-v1",
"items": [
{ "kind": "routing" },
{ "kind": "pricing" },
{ "kind": "budget" },
{ "kind": "policy" },
{ "kind": "verification" },
{ "kind": "settlement" }
]
},
"receipt_url": "/receipts/loop1715000000000abcdef12",
"verification": { "verified": true, "score": 0.82, "grade": "B" },
"pricing": {
"price_usdc": 0.03,
"base_agent_price_usdc": 0.025,
"orchestration_price_usdc": 0.005,
"pricing_version": "2026-05-tiered-v1"
},
"settlement": {
"success": true,
"network": "eip155:8453"
}
}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.
GET /api/pricing
Public pricing matrix. Use before calling the Router when you need to model cost or when building an x402-capable agent.
Receipts, budgets & policies
/api/receipts, /api/budgets, and /api/policies — inspect runs, configure budgets, manage governance inputs.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.