For Builders — Technical Reference
Learn the control plane first
Attestify OS is the hosted x402-paid agent spend router and execution control plane on Base. The main builder path is POST /api/run, which routes work, applies budgets and policies, executes, settles payment, stores a receipt, and returns pricing, evidence, verification, and settlement metadata.
These docs start with concepts so builders understand the system correctly, then provide a compact endpoint index for direct implementation work.
Hosted public defaults
asset USDC on eip155:8453
pay_to 0x8A9F22…45b25F
routing_version 2026-05-routing-v1
pricing_version 2026-05-tiered-v1
governance_version 2026-05-governance-v1
evidence_version 2026-05-evidence-v1
Default path
/api/run
The main hosted entry point for router-first paid execution.
Pricing model
Base + orchestration
Paid run price combines lane base price and orchestration fee.
Governance inputs
Budgets + policies
Control whether a run proceeds, warns, downgrades, or is blocked.
Audit surfaces
Receipts + evidence
Inspect what was routed, charged, enforced, and settled.
Recommended reading order: get your API key at /onboarding first, then understand router-first execution, pricing, governance, receipts and evidence, and finally use the endpoint index for implementation details.
Important default: public guidance should stay centered on
POST /api/run. Lower-level surfaces like POST /api/loop are useful, but they are not the main first-run integration path.Router-first execution
The core Attestify OS mental model: send a task, let the router select or confirm the agent lane, evaluate governance, execute the work, settle payment, and return structured evidence around what happened.
POST /api/run
Content-Type: application/json
X-API-Key: atst_your_key_here
{
"session_id": "docs-page-001",
"task": "Research the latest x402 adoption trends and summarize the major patterns.",
"preferred_agent_id": "researcher-v2",
"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-docs-page-001"
}Complete POST /api/run response
Every successful run returns a single JSON object. All top-level keys are shown below — destructure exactly what you need.
HTTP 200 OK
{
"status": "success", // "success" | "error"
"loop_id": "loop1715000000000abcdef12", // primary run identifier
"run_id": "run_9kXm2pQvZ", // shorter alias; same run
"lane_id": "researcher-v2", // lane that executed the task
"result": {
"output": "…model response text…",
"model": "gpt-4o",
"tokens_used": 812
},
"pricing": {
"price_usdc": 0.030,
"base_lane_price_usdc": 0.025,
"orchestration_price_usdc": 0.005,
"pricing_version": "2026-05-tiered-v1",
"cost_model": "2026-05-cost-v1"
},
"routing": {
"selected_lane": "researcher-v2",
"routing_version": "2026-05-routing-v1",
"confidence": 0.94,
"fallback_used": false
},
"budget_outcome": {
"outcome": "approved", // "approved" | "warning" | "downgrade" | "blocked" | "rejected"
"budget_id": "budget_research_monthly",
"evaluated_at": "2026-06-18T11:20:00Z"
},
"policy_applied": {
"policies_matched": ["policy_research_evidence"],
"mode": "default",
"outcome": "approved"
},
"verification": {
"verified": true,
"score": 0.82,
"grade": "B"
},
"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" }
]
},
"memory": {
"read": true,
"written": true,
"session_id": "docs-page-001"
},
"receipt_url": "/receipts/loop1715000000000abcdef12",
"settlement": {
"success": true,
"network": "eip155:8453",
"tx_hash": "0xabc123…",
"paid": true,
"simulated": false
},
"idempotency_key": "idem-docs-page-001"
}Pricing and paid runs
The final charged amount is the selected lane base price plus the orchestration fee. The definitive charged value appears in the returned pricing block from a paid run.
paid_run_price_usdc = base_lane_price_usdc + orchestration_price_usdc Example: researcher-v2 = 0.025 + 0.005 = 0.030 USDC
{
"pricing": {
"price_usdc": 0.03,
"base_lane_price_usdc": 0.025,
"orchestration_price_usdc": 0.005,
"pricing_version": "2026-05-tiered-v1",
"cost_model": "2026-05-cost-v1"
}
}Budgets and policies
Governance is part of the execution flow. Budget and policy inputs can allow, warn, downgrade, or block execution, reflected in budget_outcome and policy_applied.
Budget outcome
Records whether the planned run passed budget checks, triggered a warning, was blocked, or recommended a downgrade before spend.
Policy application
Captures which policies matched, which modes applied, and whether extra evidence or enforcement conditions were required.
Idempotent retries
Use idempotency_key for safer retries so repeated submissions can be deduplicated and tracked consistently.
Receipts, evidence, and verification
A completed run is auditable. Attestify returns a receipt reference, structured evidence items, verification signals, and settlement details.
{
"receipt_url": "/receipts/loop1715000000000abcdef12",
"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" }
]
},
"verification": { "verified": true, "score": 0.82, "grade": "B" },
"settlement": { "success": true, "network": "eip155:8453" }
}Error code reference
Every error response follows the shape {"error": "…", "code": "…", "status": 4xx}. Handle by code, not by message string.
| HTTP | code | Meaning | Recovery |
|---|---|---|---|
| 400 | invalid_request | Malformed JSON or missing required field (task, lane_id, etc.) | Fix the request payload. Check required fields against the schema above. |
| 401 | unauthorized | Missing or invalid X-API-Key header. | Include a valid atst_ key. Provision one at /onboarding. |
| 402 | payment_required | x402 challenge — payment metadata returned, no run executed. | Submit a paid POST with the X-PAYMENT header. See x402 flow. |
| 403 | forbidden | Key exists but lacks permission for this endpoint or lane. | Upgrade your plan or check lane access for your key tier. |
| 404 | not_found | Lane ID, receipt ID, budget ID, or policy ID does not exist. | Verify the ID with GET /api/lanes, /api/receipts, or /api/budgets. |
| 409 | idempotency_conflict | A run with this idempotency_key already completed with different params. | Use a new idempotency_key, or omit it to allow a fresh run. |
| 422 | budget_blocked | Budget governance blocked the run before execution. | Raise max_price_usdc, set strict: false, or adjust the budget record. |
| 422 | policy_blocked | A matched policy blocked the run. | Review policy_ids in the request, or update the policy via /api/policies. |
| 429 | rate_limited | Too many requests. Per-key rate limit exceeded. | Back off exponentially. Default limit: 60 req/min per key. |
| 500 | execution_error | Lane execution failed after payment was accepted. | Retry with the same idempotency_key — the run will not be double-charged. |
| 502 | upstream_error | Upstream model or provider returned an error. | Retry after a short delay. Check /api/health for lane status. |
| 503 | lane_unavailable | The requested lane is temporarily offline. | Use the router (omit preferred_agent_id) to fall back to an available lane. |
Endpoint index
Once the model is clear, these are the main public surfaces to implement against.
Execution
POST /api/run
Default x402-paid router endpoint. Accepts task, routing preferences, budget and policy governance inputs, then returns decision, pricing, evidence, verification, memory, receipt, and settlement metadata.
POST /api/loop
Lower-level paid execution primitive for direct loop control and backwards compatibility. Keep public integrations centered on /api/run by default.
Financial control plane
POST /api/keys
Provision a tenant API key. Supply org name, email, and plan. Returns an atst_ prefixed key to set as X-API-Key on every subsequent request.
GET | POST | PUT | DELETE /api/budgets
List, create, update, or archive budget records that can later be referenced by /api/run to cap or warn on spend.
GET | POST | PUT | DELETE /api/policies
List, create, update, or archive policy records that can later be referenced by /api/run for governance enforcement.
POST /api/subscribe
Purchase subscription plans for discounted or expanded Attestify usage.
GET /api/subscriptions
List active subscriptions for the authenticated tenant.
GET /api/tenant/analytics
Tenant-scoped spend analytics: loop counts, total USDC spent, agent usage breakdown, and budget consumption over time.
GET | POST | DELETE /api/webhooks
Register, list, or remove webhook endpoints to receive real-time events for run completions, budget warnings, and policy violations.
GET | POST /api/sla
Define and inspect SLA policies for agent lanes — latency targets, uptime expectations, and breach escalation rules.
Inspect & audit
GET /api/pricing
Public pricing matrix for current lane base prices, orchestration fee, and hosted paid run prices.
GET /api/receipts
List recent stored receipts with optional filters such as session, agent, status, paid, or verified.
GET /api/receipts/{id}
Fetch a stored run receipt by loop_id or run_id returned from /api/run.
Programmatic habit: provision a key at /onboarding, preview hosted prices with
GET /api/pricing, run work through POST /api/run, and use receipts, budgets, and policies to inspect and govern spend over time.