REST API Reference

All orbserv API endpoints are available at:

https://api.orbserv.co/v1

Authentication

Include your API key in every request:

Authorization: Bearer orb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

All requests and responses use application/json.

Auth

POST /auth/register

Create a new orbserv account.

Request body

| Field | Type | Required | Description | |-------|------|----------|-------------| | email | string | Yes | Account email address | | password | string | Yes | Password (min 12 characters) | | name | string | No | Display name |

Response 201

{
  "userId": "usr_abc123",
  "email": "[email protected]",
  "createdAt": "2025-01-15T10:00:00Z"
}

POST /auth/login

Obtain an access token.

Request body

| Field | Type | Required | |-------|------|----------| | email | string | Yes | | password | string | Yes |

Response 200

{
  "accessToken": "eyJ...",
  "expiresIn": 3600
}

Wallets

GET /wallets

List all wallets for the authenticated account.

Response 200

[
  {
    "id": "wlt_abc123",
    "name": "research-agent",
    "evm": { "address": "0x..." },
    "solana": { "address": "..." },
    "createdAt": "2025-01-15T10:00:00Z"
  }
]

POST /wallets

Create a new wallet.

Request body

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Wallet name | | chains | string[] | Yes | e.g. ["solana", "base"] | | metadata | object | No | Arbitrary key-value metadata |

Response 201 — full WalletRecord object.

GET /wallets/:id

Fetch a single wallet by ID.

Response 200 — WalletRecord.

Response 404 — wallet not found.

DELETE /wallets/:id

Archive a wallet. Archived wallets cannot send transactions but their history is preserved.

Response 204 — no content.

Transactions

GET /wallets/:id/transactions

List transactions for a wallet.

Query parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | limit | number | 20 | Max records (up to 100) | | offset | number | 0 | Pagination offset | | chain | string | — | Filter by chain | | type | string | — | send, receive, or x402 |

Response 200

{
  "data": [
    {
      "id": "tx_xyz789",
      "type": "send",
      "amount": "5.00",
      "token": "USDC",
      "chain": "base",
      "to": "0xRecipient...",
      "from": "0xSender...",
      "txHash": "0x...",
      "timestamp": "2025-01-15T12:30:00Z",
      "status": "confirmed"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

API Keys

GET /api-keys

List all API keys for the account.

Response 200

[
  {
    "id": "key_abc123",
    "name": "prod-agent",
    "createdAt": "2025-01-10T09:00:00Z",
    "lastUsed": "2025-01-15T11:45:00Z"
  }
]

Note: the full key value is only returned at creation time.

POST /api-keys

Create a new API key.

Request body

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Descriptive name for the key |

Response 201

{
  "id": "key_def456",
  "name": "staging-worker",
  "key": "orb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "createdAt": "2025-01-15T12:00:00Z"
}

Store the key value immediately — it will not be shown again.

DELETE /api-keys/:id

Revoke an API key. Revocation is immediate and irreversible.

Response 204 — no content.

Error format

All errors follow a consistent shape:

{
  "error": {
    "code": "PolicyViolation",
    "message": "Transaction exceeds dailyLimit of $10.00 (used: $9.50)",
    "requestId": "req_abc123"
  }
}

Common error codes: Unauthorized, NotFound, PolicyViolation, InsufficientFunds, ValidationError, RateLimitExceeded.