Authentication

Create an API key, then include it in every request as x-api-key header.

Endpoint	Description	Cost
POST/v1/auth/keys	Create API key (wallet address + label)	Free

Create API Key

curl -X POST https://api.xorb.xyz/v1/auth/keys \
  -H "Content-Type: application/json" \
  -d '{"owner_address": "0xYOUR_WALLET", "label": "my-project"}'

Response

{
  "success": true,
  "data": {
    "api_key": "xorb_sk_...",
    "warning": "Store this key securely. It cannot be retrieved again."
  }
}

Agents

Endpoint	Description	Cost
POST/v1/agents	Register a new agent	$0.10
GET/v1/agents	List your agents (filtered by API key)	Free
GET/v1/agents/:id	Get agent details	Free
PATCH/v1/agents/:id	Pause / resume / renew agent	Free
DELETE/v1/agents/:id	Revoke agent (permanent)	Free

Register Agent

curl -X POST https://api.xorb.xyz/v1/agents \
  -H "x-api-key: xorb_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "my-bot", "scope": "data analysis", "sponsor_address": "0x...", "description": "Fetches on-chain data"}'

Actions (8-Gate Pipeline)

Every action passes through 8 sequential security gates. If any gate fails, the action is blocked.

Endpoint	Description	Cost
POST/v1/actions/execute	Execute action through 8-gate pipeline	$0.005
POST/v1/actions/batch	Batch execute (max 100)	$0.003/ea

Execute Action

curl -X POST https://api.xorb.xyz/v1/actions/execute \
  -H "x-api-key: xorb_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent_xxx", "action": "query", "tool": "get_balance", "params": {"address": "0x..."}}'

Response (Approved)

{
  "approved": true,
  "action_id": "act_abc123...",
  "gates": [
    {"gate": "identity", "passed": true},
    {"gate": "permissions", "passed": true},
    {"gate": "rate_limit", "passed": true},
    {"gate": "x402_payment", "passed": true},
    {"gate": "audit_log", "passed": true},
    {"gate": "trust_score", "passed": true},
    {"gate": "execute", "passed": true},
    {"gate": "escrow_check", "passed": true}
  ],
  "audit_hash": "0x5e96...",
  "latency_ms": 45
}

Reputation & Trust

Endpoint	Description	Cost
GET/v1/reputation/:id	Agent reputation score + tier	$0.001
GET/v1/reputation/leaderboard	Top 100 agents by trust score	Free
GET/v1/audit/:id	Audit log for agent	$0.01
GET/v1/compliance/:id	Compliance report (EU AI Act, NIST, SOC2)	$1.00

Events

Endpoint	Description	Cost
GET/v1/events	List events (filterable by agent_id, type)	Free
GET/v1/events/stream	Long-polling event stream	Free

Webhooks

Endpoint	Description	Cost
POST/v1/webhooks	Subscribe to events	$0.10
GET/v1/webhooks	List subscriptions	Free
DELETE/v1/webhooks/:id	Remove subscription	Free

Marketplace

Endpoint	Description	Cost
GET/v1/marketplace/listings	Browse agents for hire	Free
POST/v1/marketplace/listings	List your agent for hire	Free
POST/v1/marketplace/hire	Hire an agent (escrow)	$0.05

Pricing & Payments

Endpoint	Description	Cost
GET/v1/pricing	Full pricing table	Free
GET/v1/health	API status	Free
GET/v1/integrations	Orchestrated services	Free

Error Codes

Status	Code	Meaning
401	missing_api_key	No x-api-key header provided
402	payment_required	x402 USDC payment needed
403	forbidden	You don't own this agent
404	not_found	Agent or resource not found
429	rate_limited	Too many requests (see Retry-After header)

SDK

npm install xorb-sdk

import { XorbClient } from 'xorb-sdk'

const xorb = new XorbClient({ apiKey: 'xorb_sk_...' })

// Register agent
const agent = await xorb.agents.register({
  name: 'my-bot', role: 'RESEARCHER',
  sponsor_address: '0x...'
})

// Execute action
const result = await xorb.actions.execute({
  agent_id: agent.agentId,
  action: 'query', tool: 'get_balance'
})

console.log(result.approved, result.audit_hash)