API Authentication

This guide explains how to authenticate with the Ekiden API using either a JWT or an API key.

1. Obtain a JWT

Request a JWT access token from the authorization endpoint.

POST /api/v1/authorize
Content-Type: application/json

Example request:

{
   "public_key": "<Canton Party ID>",
  "signature": "",
  "timestamp_ms": 1731541800000,
  "nonce": "random-unique-string"
}

Where:

public_key – Your Canton Party ID.
signature – "".
timestamp_ms – Current Unix timestamp in milliseconds.
nonce – A unique random string.

Example response:

{
  "token": "<jwt>",
  "user_id": "<user_id>"
}

2. API Key Authentication

For server-to-server integrations, you can authenticate requests directly using an API key. Required headers:

X-API-KEY – Your API public key.
X-SIGNATURE – Ed25519 signature of EKIDEN_API|{method}|{uri}|{timestamp_ms}|{nonce}.
X-TIMESTAMP-MS – Current Unix timestamp in milliseconds.
X-NONCE – A unique random string.

3. Authenticate REST Requests

Include the JWT as a Bearer token in the Authorization header.

GET /api/v1/user/sub-accounts
Authorization: Bearer <jwt>

4. Authenticate a Private WebSocket Connection

Connect to the private WebSocket endpoint:

wss://api.cnt.ekiden.fi/ws/private

Authenticate immediately after connecting. Client → Server

{
  "op": "auth",
  "bearer": "<jwt>",
  "req_id": "auth-1"
}

Server → Client

{
  "op": "auth",
  "success": true,
  "user_id": "<user_id>",
  "req_id": "auth-1"
}

After successful authentication, subscribe to private topics.

{
  "op": "subscribe",
  "args": [
    "order",
    "position",
    "execution",
    "account_balance"
  ],
  "req_id": "sub-1"
}

Public topics such as:

orderbook.1.BTC-USDCx
trade.BTC-USDCx
ticker.BTC-USDCx

are available on /ws/public without authentication.

Timestamp and Nonce Requirements

timestamp_ms must represent the current Unix time in milliseconds.
Each authorization request must use a unique nonce.
Requests with expired timestamps or reused nonces may be rejected.

Example (curl)

Request a JWT:

curl -X POST "https://api.cnt.ekiden.fi/api/v1/authorize" \
  -H "Content-Type: application/json" \
  -d '{
    "public_key": "<public_key>",
    "signature": "<signature>",
    "timestamp_ms": 1731541800000,
    "nonce": "random-unique-string"
  }'

Call a private endpoint:

curl \
  -H "Authorization: Bearer <jwt>" \
  "https://api.cnt.ekiden.fi/api/v1/user/sub-accounts"

Troubleshooting

Problem	Possible cause
`400 Bad Request`	Invalid request payload, expired `timestamp_ms`, or invalid `nonce`.
`401 Unauthorized`	Missing, expired, or invalid JWT.
WebSocket authentication failed	Authenticate before subscribing to private topics on `/ws/private`.

Overview

Getting Started

Setup

Fund Your Account

Market Data

Trade

Market Make

Account & Portfolio

Access Controls

Troubleshooting

RESTful API

WebSocket Guide

Websoket Reference (AsyncAPI)

1. Obtain a JWT

2. API Key Authentication

3. Authenticate REST Requests

4. Authenticate a Private WebSocket Connection

Timestamp and Nonce Requirements

Example (curl)

Troubleshooting

​1. Obtain a JWT

​2. API Key Authentication

​3. Authenticate REST Requests

​4. Authenticate a Private WebSocket Connection

​Timestamp and Nonce Requirements

​Example (curl)

​Troubleshooting

1. Obtain a JWT

2. API Key Authentication

3. Authenticate REST Requests

4. Authenticate a Private WebSocket Connection

Timestamp and Nonce Requirements

Example (curl)

Troubleshooting