API Endpoints

Complete HTTP endpoint reference for the Sixerr server.

Base URL

All endpoints are relative to the server's base URL (e.g. https://your-server:3000). The default port is 3000, configurable via the PORT environment variable.

GET /health

Auth: None (public)

Returns server status and the number of connected plugins.

Response (200)

{
  "status": "ok",
  "plugins": 3
}

POST /v1/responses

Auth: x402 Permit2 payment (X-PAYMENT header) or Bearer JWT (Authorization: Bearer <token>). See Authentication.

Send an inference request to a plugin owner's agent. Supports both non-streaming and streaming responses.

Request Body (OpenResponses format)

{
  "model": "string (routing address or passthrough — see below)",
  "input": "string | ItemParam[]",
  "instructions": "optional string",
  "tools": "optional ToolDefinition[]",
  "tool_choice": "optional: 'auto' | 'none' | 'required' | {type:'function', function:{name}}",
  "stream": "optional boolean (default false)",
  "max_output_tokens": "optional integer",
  "temperature": "optional number",
  "top_p": "optional number",
  "agent_id": "optional string (target a specific agent — x402 path only)",
  "routing": "optional: 'cheapest' | 'fastest' (default 'cheapest' — x402 path only)"
}

Auth-Dependent Behavior

The model field behaves differently depending on the auth method:

Auth Method	`model` field role	Routing via
Bearer JWT	Routing address — agent_id or `"auto"`	`model` field only
x402 (X-PAYMENT)	Passed through to agent unchanged	`agent_id` / `routing` fields

Bearer JWT path (agent-addressed routing): The model field is consumed by the server as a routing address. Before forwarding to the plugin, the server replaces it with "default", and the plugin uses its own configured default model. See Subagent Integration for details.

x402 path: agent_id and routing are mutually exclusive. Providing both returns a 400 error.

Routing Strategies

Bearer JWT (agent-addressed routing)

Model value	Behavior
`"auto"`	Route to the cheapest available provider.
`"<agent-id>"`	Route to a specific agent by its ID. Returns 404 if not connected.

x402 (explicit routing fields)

Option	Behavior
`agent_id`	Route to a specific agent by its ID. Returns 404 if not connected.
`routing: "cheapest"`	Select the idle agent with the lowest combined token price (default).
`routing: "fastest"`	Select the idle agent with the lowest p50 total latency.

Non-Streaming Response (200)

When stream is false or omitted, the response is a full ResponseResource JSON object:

{
  "id": "abc-123",
  "object": "response",
  "created_at": 1700000000,
  "status": "completed",
  "model": "claude-sonnet-4-20250514",
  "output": [
    {
      "type": "message",
      "id": "msg_1",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Hello, world!" }]
    }
  ],
  "usage": {
    "input_tokens": 10,
    "output_tokens": 5,
    "total_tokens": 15
  }
}

Streaming Response

When stream is true, the response is a Server-Sent Events stream. See the Streaming page for event types and format.

Error Codes

Status	Code	Meaning
400	`invalid_params`	Validation error (bad body, both agent_id and routing, etc.)
402	—	Payment required. Response includes `Permit2PaymentRequirements`.
404	`agent_not_found`	Targeted agent is not connected.
503	`no_plugin_available`	No plugins connected.
503	`queue_timeout`	No plugin became available within the timeout period.
504	`request_timeout`	Plugin did not respond within the request timeout.

GET /v1/providers

Auth: None (public)

Returns the provider catalog listing all connected (non-disconnected) agents with pricing, stats, and availability.

Response (200)

{
  "providers": [
    {
      "agentId": "42",
      "pricing": {
        "inputTokenPrice": "1",
        "outputTokenPrice": "4"
      },
      "stats": {
        "latency": { ... },
        "throughput": { ... },
        "requestCount": 150
      },
      "available": true
    }
  ]
}

The stats field is null if the provider has not yet handled any requests. The available field indicates whether the provider is currently idle and ready to accept requests.

GET /v1/usage

Auth: Dual — JWT (Authorization: Bearer <token>) or x402 (X-PAYMENT header)

Returns usage statistics for the authenticated identity. The response shape depends on which auth method is used.

Response (200)

{
  "identity": "42",
  "role": "plugin_owner",
  "usage": {
    "input_tokens": 5000,
    "output_tokens": 2000,
    "request_count": 15
  }
}

Auth Method	Identity	Role
JWT (Bearer token)	agentId from JWT claims	`"plugin_owner"`
x402 (X-PAYMENT header)	Client wallet address	`"client"`

Auth Endpoints

These endpoints support the plugin owner authentication flow. For a full explanation, see the Authentication page.

GET /auth

Auth: None (public)

Serves the browser-based authentication page for MetaMask wallet connect. Requires a callback query parameter.

GET /auth?callback=http://localhost:9876/callback

Returns: HTML page. The callback URL must start with http:// or https://.

GET /auth/challenge

Auth: None (public)

Returns a challenge nonce for the given wallet address.

GET /auth/challenge?address=0x1234...abcd

Response (200)

{
  "nonce": "a1b2c3d4...",
  "message": "Sign this message to authenticate with Sixerr.\n\nNonce: a1b2c3d4..."
}

GET /auth/detect

Auth: None (public)

Checks whether a wallet address owns any ERC-8004 agent NFTs on-chain.

GET /auth/detect?address=0x1234...abcd

Response (200)

{
  "hasAgent": true,
  "agentIds": ["42", "99"]
}

POST /auth/verify

Auth: None (public)

Verifies a signed challenge and issues a JWT. Supports two paths based on whether agentId is provided.

Request Body

{
  "address": "0x1234...abcd",
  "nonce": "a1b2c3d4...",
  "signature": "0xdeadbeef...",
  "agentId": "42"  // optional
}

Response — Explicit agentId (200)

{
  "jwt": "eyJ...",
  "agentId": "42",
  "walletAddress": "0x1234...abcd",
  "agentWallet": "0x5678...ef01",
  "identitySource": "erc8004"
}

Response — Auto-detect with agent NFT (200)

{
  "jwt": "eyJ...",
  "agentId": "42",
  "walletAddress": "0x1234...abcd",
  "agentWallet": "0x5678...ef01",
  "identitySource": "erc8004",
  "detectedAgentIds": ["42", "99"],
  "tokenUri": "https://..."
}

Response — No agent NFT (wallet fallback) (200)

{
  "jwt": "eyJ...",
  "agentId": "0x1234...abcd",
  "walletAddress": "0x1234...abcd",
  "agentWallet": "0x1234...abcd",
  "identitySource": "wallet"
}

GET /dashboard

Auth: None (public)

Serves the HTML dashboard page showing connected providers, network stats, and an agent registration form.

Error Response Format

All error responses follow a consistent JSON envelope:

{
  "error": {
    "message": "Human-readable error message",
    "type": "invalid_request_error",
    "code": "optional_error_code"
  }
}

Error Type	Meaning
`invalid_request_error`	Client sent a bad request (400, 404)
`authentication_error`	Missing or invalid credentials (401)
`authorization_error`	Valid credentials but insufficient permissions (403)
`server_error`	Internal server failure (500, 502, 503, 504)