Getting Started

ARCXS is a REST API. Every AI agent, framework, or application can integrate using standard HTTP. No special SDK required — or use the MCP server for native tool integration. Register an agent, run discovery queries, translate between protocols, and route payments with a few simple calls.

Base URL

https://arcxs.net/api/v1

Quick registration: 3 steps

• Generate an API key via POST /api/v1/keys/generate
• Register your agent via POST /api/v1/agents with your key in the Authorization header
• Send a heartbeat every 60 seconds to stay discoverable

Response format

All responses are JSON. Successful responses return the relevant data object. Errors follow a consistent structure:

{
  "error": {
    "code":      "INVALID_PROTOCOL",
    "message":   "Protocol 'xyz' is not supported",
    "timestamp": 1743000000000
  }
}

Authentication

Write operations (register, update, delete, send messages) require an API key. Read operations (lookup, search, discovery) are public and require no authentication.

Generating a key

Call POST /api/v1/keys/generate with your agent address and desired permissions. You'll receive a key prefixed with arcxs_.

Using your key

Authorization: Bearer arcxs_your_key_here

Permission scopes

• agent:create — Register a new agent
• agent:update — Update registration or send heartbeats
• agent:delete — Remove an agent from the registry
• message:send — Send messages via the queue
• billing:manage — Subscribe, renew, or cancel

Rate Limits

Rate limits are applied per IP address. Limits vary by operation type:

• Read operations (lookup, search, discovery) — generous limits, designed for frequent polling
• Write operations (register, update, delete) — tighter limits to prevent abuse
• Key generation — strictly limited to prevent automated abuse

Exceeding limits returns 429 Too Many Requests with a Retry-After header.

Error Responses

• 400 — Bad Request (validation failed, missing fields)
• 401 — Unauthorized (missing or invalid API key)
• 403 — Forbidden (key lacks required permission scope)
• 404 — Not Found (agent address doesn't exist)
• 409 — Conflict (agent address already registered)
• 429 — Too Many Requests (rate limit exceeded)
• 500 — Internal Server Error

Agents

The registry: register, look up, search, update, and manage AI agents. Agent addresses follow the format name.namespace.agent (e.g. weather.myapp.agent).

Discovery

Full-text search, trending agents, protocol filtering, and analytics. All discovery endpoints are public. No API key required.

Protocol Translation

ARCXS bridges x402, A2A, MCP, AP2, OpenClaw, and MPP. Translate message structure between any two supported protocols without understanding either protocol's internals. That's a 6×6 translation matrix — 30 cross-protocol paths, all live.

Supported Protocols

Messages

Store-and-forward message delivery between agents. Like SMTP: if the recipient is offline, the message queues and retries with exponential backoff.

Billing

Manage Registered agent subscriptions. Discovery and ephemeral registration are always free. Registered tier is $20/year or $2/month.

API Keys

Generate and manage API keys. Keys are scoped to specific permissions and are hashed at rest. Store them securely on generation.

Status

Code Examples

Common operations in Node.js, Python, and curl. ARCXS is a plain REST API. Any HTTP client works.

1. Generate a key & register an agent

// Step 1: Generate an API key
const keyRes = await fetch('https://arcxs.net/api/v1/keys/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    agent_address: 'weather.myapp.agent',
    permissions: ['agent:create', 'agent:update'],
    label: 'production-key'
  })
});
const { api_key } = await keyRes.json();

// Step 2: Register the agent
const regRes = await fetch('https://arcxs.net/api/v1/agents', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${api_key}`
  },
  body: JSON.stringify({
    address: 'weather.myapp.agent',
    name: 'Weather Agent',
    description: 'Real-time weather forecasts and alerts',
    protocol: 'mcp',
    endpoint: 'https://myapp.com/agents/weather',
    capabilities: ['forecast', 'alerts', 'historical'],
    ttl_days: 30  // free ephemeral tier
  })
});
const agent = await regRes.json();
console.log('Registered:', agent.address);

import requests

BASE = 'https://arcxs.net/api/v1'

# Step 1: Generate an API key
key_res = requests.post(f'{BASE}/keys/generate', json={
    'agent_address': 'weather.myapp.agent',
    'permissions': ['agent:create', 'agent:update'],
    'label': 'production-key'
})
api_key = key_res.json()['api_key']

# Step 2: Register the agent
reg_res = requests.post(f'{BASE}/agents',
    headers={'Authorization': f'Bearer {api_key}'},
    json={
        'address': 'weather.myapp.agent',
        'name': 'Weather Agent',
        'description': 'Real-time weather forecasts and alerts',
        'protocol': 'mcp',
        'endpoint': 'https://myapp.com/agents/weather',
        'capabilities': ['forecast', 'alerts', 'historical'],
        'ttl_days': 30
    }
)
print('Registered:', reg_res.json()['address'])

# Generate key
curl -X POST https://arcxs.net/api/v1/keys/generate \
  -H "Content-Type: application/json" \
  -d '{"agent_address":"weather.myapp.agent","permissions":["agent:create","agent:update"]}'

# Register agent (use key from above)
curl -X POST https://arcxs.net/api/v1/agents \
  -H "Authorization: Bearer arcxs_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "weather.myapp.agent",
    "name": "Weather Agent",
    "protocol": "mcp",
    "endpoint": "https://myapp.com/agents/weather",
    "ttl_days": 30
  }'

2. Discover agents

// Search for MCP agents with forecast capability
const res = await fetch(
  'https://arcxs.net/api/v1/discovery/search?q=weather&protocol=mcp&limit=10'
);
const { agents } = await res.json();
agents.forEach(a => console.log(a.address, '—', a.description));

curl "https://arcxs.net/api/v1/discovery/search?q=weather&protocol=mcp"

3. Translate a message between protocols

// Translate an MCP message to x402 format
const res = await fetch('https://arcxs.net/api/v1/translate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    from_protocol: 'mcp',
    to_protocol: 'x402',
    message: {
      type: 'tool_call',
      tool: 'get_forecast',
      input: { location: 'Seattle, WA' }
    }
  })
});
const { translated } = await res.json();

curl -X POST https://arcxs.net/api/v1/translate \
  -H "Content-Type: application/json" \
  -d '{"from_protocol":"mcp","to_protocol":"x402","message":{"type":"tool_call","tool":"get_forecast"}}'

4. Send a heartbeat (keep alive)

// Call this on startup, then every 60 seconds
async function sendHeartbeat(address, apiKey) {
  await fetch(`https://arcxs.net/api/v1/agents/${address}/heartbeat`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });
}

sendHeartbeat('weather.myapp.agent', API_KEY);
setInterval(() => sendHeartbeat('weather.myapp.agent', API_KEY), 60_000);