Authentication

Every endpoint accepts one of two credentials. The server picks the scheme from the APIKEY header: a request carrying it is verified as HMAC and never retried as a session, even if the signature is bad.

Scheme	Wire format	For
Session token	`Authorization: Bearer <token>`	Dashboards, short-lived tooling, the docs playground
API key (HMAC)	`APIKEY` + `X-Hmac-Timestamp` + `X-Hmac-Signature` headers	Trading systems

In the API playground on this site, authenticate with a session token from POST /auth/login. The HMAC scheme signs the exact request bytes and cannot be computed by the playground.

Session tokens

Exchange an email and password for a JWT:

curl -X POST https://api.symbiosis.markets/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email": "you@example.com", "password": "..."}'

Send it as a bearer token. Sessions carry every scope: read, trade, and withdraw. See Scopes for what each allows.

API keys

Mint a key from a session:

curl -X POST https://api.symbiosis.markets/auth/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"label": "trading-bot", "scopes": ["read", "trade"]}'

The response is the only time the raw secret is returned; store it then. Keys carry exactly the scopes you name at mint time, capped at the minting credential’s own scopes. A key never gains scopes later; mint a new key instead.

Scopes

Scope	Grants
`read`	Balances, deposit addresses, open requests and quotes
`trade`	Creating, quoting, cancelling, and accepting RFQs
`withdraw`	Queueing withdrawals

Signing requests

Each HMAC request sends three headers:

Header	Value
`APIKEY`	The API key id
`X-Hmac-Timestamp`	Current Unix time in milliseconds
`X-Hmac-Signature`	Base64 HMAC-SHA256 of the canonical message, keyed with the key’s secret

The canonical message is:

{timestamp_ms}\n{METHOD}\n{PATH_AND_QUERY}\n{BODY}

Three details matter:

PATH_AND_QUERY is the full request target including the query string: /rfq/quote?request_id=..., not /rfq/quote. Every GET endpoint takes its parameters from the query string, so they are inside the signature.
BODY is the exact raw bytes you transmit. Sign the serialized string you send, not a re-serialization. For bodyless requests (GETs, DELETEs without a payload) the body segment is empty; the message still ends with the third \n.
The timestamp must be within ±30 seconds of server time (the deployment’s AUTH_HMAC_TOLERANCE_SECS), which bounds the replay window.

import base64, hashlib, hmac, json, time
import requests

BASE = "https://api.symbiosis.markets"
API_KEY_ID = "..."
API_SECRET = b"..."

def signed_request(method: str, path_and_query: str, body: dict | None = None):
    raw = json.dumps(body).encode() if body is not None else b""
    ts = str(int(time.time() * 1000))

    message = ts.encode() + b"\n" + method.encode() + b"\n" \
        + path_and_query.encode() + b"\n" + raw
    signature = base64.b64encode(
        hmac.new(API_SECRET, message, hashlib.sha256).digest()
    ).decode()

    return requests.request(
        method,
        BASE + path_and_query,
        data=raw if body is not None else None,
        headers={
            "APIKEY": API_KEY_ID,
            "X-Hmac-Timestamp": ts,
            "X-Hmac-Signature": signature,
            **({"Content-Type": "application/json"} if body is not None else {}),
        },
    )

# GET with query params: the query string is part of the signature.
r = signed_request("GET", "/custody/get-usdc-balance")

# POST with a body: sign the exact bytes sent.
r = signed_request("POST", "/rfq/request", {
    "asset_id": "0x...",
    "venue_id": "polymarket",
    "amount": "1000000",
    "side": "Bid",
})

import { createHmac } from "node:crypto";

const BASE = "https://api.symbiosis.markets";
const API_KEY_ID = "...";
const API_SECRET = "...";

async function signedRequest(
  method: string,
  pathAndQuery: string,
  body?: unknown,
): Promise<Response> {
  const raw = body === undefined ? "" : JSON.stringify(body);
  const ts = Date.now().toString();

  const message = `${ts}\n${method}\n${pathAndQuery}\n${raw}`;
  const signature = createHmac("sha256", API_SECRET)
    .update(message)
    .digest("base64");

  return fetch(BASE + pathAndQuery, {
    method,
    body: body === undefined ? undefined : raw,
    headers: {
      APIKEY: API_KEY_ID,
      "X-Hmac-Timestamp": ts,
      "X-Hmac-Signature": signature,
      ...(body === undefined ? {} : { "Content-Type": "application/json" }),
    },
  });
}

Failure modes

Status	Meaning
`401`	Unknown key, timestamp outside the ±30s window, or a signature that does not verify. Check the canonical message byte for byte
`403`	Credentials verified, but the key lacks the scope the endpoint requires

A common cause of 401 is signing path while sending path?query, or letting an HTTP client re-serialize the JSON body after signing.

Websocket tickets

Browsers cannot set headers on websocket upgrades, so socket connections authenticate with a short-lived ticket passed as a ?ticket= query parameter:

POST /auth/ws-ticket: minted from a session; the ticket carries read.
POST /auth/ws-ticket/signed: HMAC-signed; the ticket inherits the key’s scopes.

Both are listed under Auth. Tickets expire in 30 seconds. Mint one immediately before connecting.

Getting started

Integration guide

Session tokens

API keys

Scopes

Signing requests

Failure modes

Websocket tickets

​Session tokens

​API keys

​Scopes

​Signing requests

​Failure modes

​Websocket tickets

Session tokens

API keys

Scopes

Signing requests

Failure modes

Websocket tickets