Conventions

This document outlines Ekiden’s API design conventions and standards. These ensure consistency, developer-friendliness, and compatibility across all REST and WebSocket interfaces.

​

1. Base URLs and Environments

Ekiden provides separate base URLs for each environment:

• Mainnet: https://api.ekiden.fi
• Testnet: https://testnet-api.ekiden.fi

All API calls must use HTTPS.

​

2. Versioning

We use URI-based versioning:

• Format: /v1/
• Example: GET /v1/orders

Backward-incompatible changes will trigger a new version (e.g., /v2/).

​

3. RESTful Design

• Resources are nouns, pluralized when appropriate
  • Example: /v1/orders, /v1/markets

​

4. WebSocket Protocol

Endpoint:

wss://ws.ekiden.exchange/v1/stream

​

Subscribe to a public channel

{
  "type": "subscribe",
  "channel": "orderbook",
  "market": "ETH-USD"
}

​

Subscribe to private (authenticated) channels

{
  "type": "subscribe",
  "channel": "orders",
  "apiKey": "your_api_key",
  "signature": "your_signature",
  "timestamp": "2025-05-10T12:34:56Z"
}

​

5. Authentication (REST)

Private endpoints require:

• EKIDEN-API-KEY
• EKIDEN-TIMESTAMP (ISO 8601 UTC)
• EKIDEN-SIGNATURE (HMAC SHA256 of timestamp + method + path + body)

​

Example headers

EKIDEN-API-KEY: your_key
EKIDEN-TIMESTAMP: 2025-05-10T12:34:56Z
EKIDEN-SIGNATURE: base64(hmac_sha256(...))

​

6. Numerical Precision

• All token quantities and prices are strings
• Up to 18 decimal places
• Use big number or decimal libraries — avoid floats

"2.000000000000000000"

​

7. Timestamps

• Format: ISO 8601 with Z (UTC)

"2025-05-10T12:34:56Z"

​

8. Error Handling

​

Error response format

{
  "error_code": 2001,
  "error_message": "Invalid signature"
}

​

Error codes

HTTP status codes (400, 401, 429, etc.) are used appropriately.

​

9. Rate Limits

• Public endpoints: 60 requests/minute
• Private endpoints: 30 requests/minute per API key

​

Example response on limit exceeded

{
  "error_code": 2003,
  "error_message": "Rate limit exceeded"
}

​

10. Pagination

Cursor-based pagination:

• Query params: limit, cursor

GET /v1/trades?limit=100&cursor=abc123

​

Response

{
  "data": [...],
  "next_cursor": "abc123"
}

​

11. Response Structure

All responses are JSON objects.

​

Success

{
  "success": true,
  "data": { ... }
}

​

Error

{
  "error_code": 2001,
  "error_message": "Invalid signature"
}

​

12. Field Naming

• All JSON keys use snake_case
• All numeric values are strings
• Timestamps are always strings in ISO 8601

​

13. WebSocket Heartbeats

To keep the connection alive:

​

Client sends

{ "type": "ping" }

​

Server responds

{ "type": "pong" }

Idle connections close after 60 seconds without activity.

For detailed endpoint specifications and integration examples, continue to the API reference.