REST API - Monaco Protocol SDK v1.0.67

Use the REST API when you want direct HTTP/JSON access from backends, scripts, custom clients, mobile apps, or API tooling. SDKs are available when you want Monaco auth, signing, and request formatting handled for you.

REST SDKs are available for TypeScript, React, and Rust. See the TypeScript SDK, React SDK, or Rust REST SDK.

Endpoint

https://staging.apimonaco.xyz/api

Base URLs

Use the staging base URL for private alpha and testnet integrations:

https://staging.apimonaco.xyz

Request Requirements

Every request must include a non-empty User-Agent header. Requests that send an empty or absent User-Agent are rejected at the edge with 403 Forbidden before reaching the API.

Official SDKs set a User-Agent automatically. Direct HTTP clients — curl, shell scripts, and generated or custom clients — must set one explicitly, or requests will be rejected.

curl -H 'User-Agent: my-app/1.0' -H 'Accept: application/json' \
  'https://staging.apimonaco.xyz/api/v1/market/pairs?isActive=true&pageSize=100'

Routes

The generated route pages in this section are the source of truth for request parameters, request bodies, responses, and authentication headers. Use the left navigation to browse by endpoint group, or start with the health check route.

OpenAPI

Every route page in this section is generated from Monaco’s OpenAPI specification, so the documented parameters, request bodies, responses, and authentication headers always match the live API. Public market-data routes can be called without authentication. Account, order, withdrawal, and margin routes require a wallet-authorized ed25519 session key.

Authentication Flow

Monaco authenticates with a wallet-authorized ed25519 session key. The wallet signs once to authorize a session key; every authenticated request is then signed with that key.

Generate a session key -> create an ed25519 keypair locally.
Create challenge -> request a nonce, passing the session public key.
Sign message -> sign the challenge message with the wallet.
Verify signature -> Monaco registers the session public key and opens a session.
Sign requests -> sign each subsequent request with the session private key.

There are no access or refresh tokens.

Authenticating Requests

Every authenticated request is signed with the session private key. Two protocols are accepted over the same key: the legacy X-Monaco-* headers below, and opt-in RFC 9421 HTTP message signatures. Send one or the other: a request carrying Signature or Signature-Input alongside any X-Monaco-* header is rejected with 401. Content-Digest is not a credential and may accompany a legacy-signed request on its own. For legacy signing, set three headers:

Header	Value
`X-Monaco-PublicKey`	64-char lowercase-hex session public key
`X-Monaco-Timestamp`	Unix timestamp in milliseconds, within 30 seconds of server time
`X-Monaco-Signature`	Hex ed25519 signature over the signing string

The signing string is built from the request:

METHOD\npath?query\ntimestamp_ms\nSHA256_hex(body)

METHOD — uppercase HTTP method, such as GET or POST.
path?query — request path including query string, exactly as sent.
timestamp_ms — the same value sent in X-Monaco-Timestamp.
SHA256_hex(body) — hex SHA-256 of the raw request body, or of the empty byte string when there is no body.

For RFC 9421 signing, send Signature-Input, Signature, and Content-Digest instead. Monaco verifies a bounded profile — the label monaco, the components @method, @path, @query, content-digest in that order, created in Unix seconds within 30 seconds of server time, and alg="ed25519" — and never falls back to legacy verification when it fails. The HTTP message signatures reference has the complete profile and signature base. Because the body hash is signed, a captured request cannot be reused with a modified body, and the timestamp bounds how long it remains valid. Freshness is an anti-stale control, not an anti-replay one: an identical signed request can be accepted again inside the window, and Monaco keeps no nonce or replay cache. Where an endpoint takes an idempotencyKey — order creation and batch creation do — treat it as required rather than optional on any retry, and reuse the original key and payload. An endpoint without one carries no exactly-once guarantee, so do not blindly retry a write against it. SDKs handle signing automatically. Use direct REST only when you need a custom client.

Network Configuration

The API base URL determines which network you’re targeting. Network configuration (vault contract, chain settings) is handled server-side for security.

Staging (Testnet): https://staging.apimonaco.xyz - Sei Testnet (chain ID 1328)

Enum Value Formats

Monaco API uses consistent uppercase formatting for all enum values. Use these exact values in your requests:

Market Types & Trading Modes

SPOT - Spot trading (uppercase)

Order Types

LIMIT - Limit order (uppercase)
MARKET - Market order (uppercase)

Order Sides

BUY - Buy order (uppercase)
SELL - Sell order (uppercase)

Order Status

SUBMITTED - Order submitted to matching engine
PARTIALLY_FILLED - Partially executed
FILLED - Fully executed (match complete, pending settlement)
SETTLED - Settlement initiated
SETTLED_ON_CHAIN - Fully settled on-chain (terminal state)
CANCELLED - Order cancelled
EXPIRED - Order expired (GTC orders expire after 90 days by default)
REJECTED - Order rejected

Note: All enum values use uppercase format with underscores for consistency across the API.

Authentication Endpoints

1. Create Authentication Challenge

Creates a unique challenge that must be signed by the user’s wallet.

POST /api/v1/auth/challenge

Request Body:

{
  "address": "0x742d35Cc6634C0532925a3b8D4060f31E2C3d8B5",
  "clientId": "688a21440e304c06b935f743dae88278",
  "sessionPublicKey": "3b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29"
}

Response:

{
  "nonce": "abc123def456",
  "message": "Please sign this message to authenticate with Monaco Protocol: abc123def456",
  "expiresAt": 1703875200
}

Request Fields:

address (string, required) - User’s Ethereum wallet address
clientId (string, optional) - Your application’s public client ID
sessionPublicKey (string, required) - 64-char lowercase-hex ed25519 session public key generated locally. The returned message embeds this key so the wallet signature authorizes it.

Response Fields:

nonce (string) - Unique challenge identifier
message (string) - Message to sign with wallet
expiresAt (number) - Challenge expiration timestamp (Unix)

2. Verify Signature

Verifies the signed challenge, registers the session public key, and opens a session.

POST /api/v1/auth/verify

Request Body:

{
  "address": "0x742d35Cc6634C0532925a3b8D4060f31E2C3d8B5",
  "signature": "0x1234567890abcdef...",
  "nonce": "abc123def456",
  "clientId": "688a21440e304c06b935f743dae88278",
  "sessionPublicKey": "3b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29"
}

Response:

{
  "expiresAt": 1703878800,
  "user": {
    "id": "user-123",
    "address": "0x742d35Cc6634C0532925a3b8D4060f31E2C3d8B5",
    "username": "testuser"
  }
}

Request Fields:

address (string, required) - Ethereum wallet address that signed the message
signature (string, required) - Hex-encoded signature from wallet
nonce (string, required) - Nonce from the challenge request
clientId (string, optional) - Your application’s public client ID
sessionPublicKey (string, required) - Same 64-char hex session public key sent to /auth/challenge; the server binds it to the new session

Response Fields:

expiresAt (number) - Session expiration timestamp (Unix)
user (object) - Authenticated user information (id, address, username)

No tokens are returned. Sign subsequent requests with the session private key matching sessionPublicKey — see Authenticating Requests.

3. Refresh Session

Extends the current session’s expiry. The request carries no body and is authenticated with the standard signing headers.

POST /api/v1/auth/refresh

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE

Response:

{
  "expiresAt": 1703882400
}

4. Revoke Session

Revokes the current session. The request carries no body and is authenticated with the standard signing headers. The user will need to authenticate again.

POST /api/v1/auth/revoke

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE

Response:

{
  "message": "Session revoked successfully"
}

Note: This endpoint revokes the session identified by the signing key on the request.

Account Endpoints

All account endpoints require a signed request — see Authenticating Requests.

5. Get User Profile

Retrieves the current user’s core profile metadata. Does not include balances, movements, or orders — use the dedicated endpoints for those.

GET /api/v1/accounts/me

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE

Response:

{
  "id": "user-123",
  "address": "0x742d35Cc6634C0532925a3b8D1B9d7c2bd34e8Dc",
  "username": null,
  "accountType": "master",
  "canWithdraw": true,
  "createdAt": "2024-01-15T10:30:00Z"
}

Fields:

id (string) - User unique identifier
address (string) - User wallet address
username (string, optional) - User’s display name
accountType (string) - Account type: “master” or “sub”
canWithdraw (boolean) - Whether user can withdraw
createdAt (string) - Account creation timestamp (ISO 8601, UTC)

6. Get User Balances

Retrieves the current user’s token balances with pagination support.

GET /api/v1/accounts/balances?page=1&pageSize=20

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE

Query Parameters:

page (number, optional) - Page number, starts from 1 (default: 1)
pageSize (number, optional) - Items per page, max 100 (default: 20)

Response:

{
  "balances": [
    {
      "assetId": "123e4567-e89b-12d3-a456-426614174000",
      "token": "0x23e459c24c4925ba89205c400dceca7abc11723d",
      "symbol": "USDC",
      "decimals": 6,
      "availableBalance": "1000.50",
      "lockedBalance": "50.25",
      "totalBalance": "1050.75",
      "availableBalanceRaw": "1000500000",
      "lockedBalanceRaw": "50250000"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 5,
  "totalPages": 1
}

Balance Fields:

assetId (string) - Asset UUID
token (string) - Token contract address
symbol (string | null) - Token symbol (if available)
decimals (number) - Token decimals
availableBalance (string) - Available balance for trading (normalized)
lockedBalance (string) - Balance locked in open orders (normalized)
totalBalance (string) - Total balance (available + locked)
availableBalanceRaw (string) - Available balance in raw format (smallest unit)
lockedBalanceRaw (string) - Locked balance in raw format (smallest unit)

7. Get User Balance by Asset

Retrieves the current user’s balance for a specific asset. Returns zero balances if the user has no balance for a valid asset.

GET /api/v1/accounts/balances/{assetId}

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE

Path Parameters:

assetId (string) - Asset UUID (get from trading pair’s baseAssetId or quoteAssetId)

Response:

{
  "assetId": "123e4567-e89b-12d3-a456-426614174000",
  "token": "0x23e459c24c4925ba89205c400dceca7abc11723d",
  "symbol": "USDC",
  "decimals": 6,
  "availableBalance": "1000.50",
  "lockedBalance": "50.25",
  "totalBalance": "1050.75",
  "availableBalanceRaw": "1000500000",
  "lockedBalanceRaw": "50250000"
}

Error Responses:

401 Unauthorized - Authentication required
404 Not Found - Asset not found

8. Get User Movements

Retrieves the current user’s ledger movements (transaction history) with pagination and filtering support.

GET /api/v1/accounts/movements?page=1&pageSize=20&entryType=CREDIT&transactionType=DEPOSIT

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE

Query Parameters:

page (number, optional) - Page number, starts from 1 (default: 1)
pageSize (number, optional) - Items per page, max 100 (default: 20)
entryType (string, optional) - Filter by entry type
transactionType (string, optional) - Filter by transaction type
assetId (UUID, optional) - Filter by asset ID

Response:

{
  "movements": [
    {
      "id": "mov-123",
      "amount": "100.50",
      "balanceBefore": "900.00",
      "balanceAfter": "1000.50",
      "entryType": "CREDIT",
      "transactionType": "DEPOSIT",
      "description": "USDC deposit",
      "token": "0x23e459c24c4925ba89205c400dceca7abc11723d",
      "blockNumber": 18500000,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 45,
  "totalPages": 3
}

Movement Fields:

entryType (string) - Entry type
transactionType (string) - Transaction type

9. List Sub-Accounts with Balances

Lists all sub-accounts with their token balances for a master account.

GET /api/v1/accounts/sub-accounts

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE

Response:

{
  "subAccounts": [
    {
      "id": "sub-123",
      "address": "0x...",
      "username": null,
      "canWithdraw": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "balances": [
        {
          "token": "0x...",
          "symbol": "USDC",
          "decimals": 6,
          "availableBalance": "500.00",
          "lockedBalance": "0.00",
          "totalBalance": "500.00",
          "availableBalanceRaw": "500000000",
          "lockedBalanceRaw": "0"
        }
      ]
    }
  ],
  "total": 1
}

Error Responses:

401 Unauthorized - Authentication required
403 Forbidden - Only master accounts can view sub-accounts

Sub-Account Limits Endpoints

Endpoints for managing trading limits on sub-accounts. Only master accounts can manage limits for their sub-accounts.

10. Create Sub-Account Limit

Creates a new limit for a sub-account.

POST /api/v1/accounts/sub-accounts/limits

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE
Content-Type: application/json

Request Body:

{
  "subAccountId": "123e4567-e89b-12d3-a456-426614174000",
  "assetId": "123e4567-e89b-12d3-a456-426614174001",
  "maxAmount": "10000.00",
  "dailyLimit": "1000.00"
}

Request Fields:

subAccountId (string, required) - Sub-account UUID
assetId (string, required) - Asset UUID (get from trading pair’s baseAssetId or quoteAssetId)
maxAmount (string, required) - Maximum amount allowed for the sub-account
dailyLimit (string, optional) - Daily limit amount

Response:

{
  "id": "limit-123",
  "subAccountId": "123e4567-e89b-12d3-a456-426614174000",
  "masterAccountId": "master-456",
  "token": "0x23e459c24c4925ba89205c400dceca7abc11723d",
  "maxAmount": "10000.00",
  "dailyLimit": "1000.00",
  "usedToday": "0.00",
  "lastResetAt": null,
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Response Fields:

token (string) - Token contract address (resolved from assetId)
maxAmount (string) - Maximum amount allowed
dailyLimit (string, optional) - Daily limit amount
usedToday (string) - Amount used today
lastResetAt (string, optional) - Last daily reset timestamp

Error Responses:

400 Bad Request - Invalid request or limit already exists
403 Forbidden - Only master accounts can set sub-account limits
404 Not Found - Sub-account relationship not found or asset not found

11. Get Sub-Account Limits

Gets all limits for a sub-account.

GET /api/v1/accounts/sub-accounts/{subAccountId}/limits

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE

Path Parameters:

subAccountId (string) - Sub-account UUID

Response:

[
  {
    "id": "limit-123",
    "subAccountId": "123e4567-e89b-12d3-a456-426614174000",
    "masterAccountId": "master-456",
    "token": "0x23e459c24c4925ba89205c400dceca7abc11723d",
    "maxAmount": "10000.00",
    "dailyLimit": "1000.00",
    "usedToday": "250.00",
    "lastResetAt": "2024-01-15T00:00:00Z",
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
]

12. Update Sub-Account Limit

Updates an existing limit for a sub-account.

PUT /api/v1/accounts/sub-accounts/{subAccountId}/limits/{assetId}

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE
Content-Type: application/json

Path Parameters:

subAccountId (string) - Sub-account UUID
assetId (string) - Asset UUID (get from trading pair’s baseAssetId or quoteAssetId)

Request Body:

{
  "maxAmount": "15000.00",
  "dailyLimit": "2000.00",
  "isActive": true
}

Response:

{
  "id": "limit-123",
  "subAccountId": "123e4567-e89b-12d3-a456-426614174000",
  "masterAccountId": "master-456",
  "token": "0x23e459c24c4925ba89205c400dceca7abc11723d",
  "maxAmount": "15000.00",
  "dailyLimit": "2000.00",
  "usedToday": "250.00",
  "lastResetAt": "2024-01-15T00:00:00Z",
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:00:00Z"
}

13. Delete Sub-Account Limit

Deletes a limit for a sub-account.

DELETE /api/v1/accounts/sub-accounts/{subAccountId}/limits/{assetId}

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE

Path Parameters:

subAccountId (string) - Sub-account UUID
assetId (string) - Asset UUID (get from trading pair’s baseAssetId or quoteAssetId)

Response:

204 No Content

Application Configuration Endpoint

14. Get Application Configuration

Returns the configuration for the authenticated application.

GET /api/v1/applications/config

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE

Response:

{
  "id": "app-123",
  "name": "My Trading App",
  "allowedOrigins": ["https://myapp.com"],
  "webhookUrl": "https://myapp.com/webhook",
  "vaultContractAddress": "0x1234567890abcdef1234567890abcdef12345678"
}

Application Backend Endpoints

These endpoints are for backend services only and require your sk_ secret key in the x-server-key header. Pass the key directly — no token exchange needed. To get your secret key, email [email protected].

Backend Authentication Header

All backend endpoints require the server key header:

x-server-key: YOUR_SERVER_KEY

15. List Application Users (Backend Only)

Returns a paginated list of all users for this application.

GET /api/v1/applications/users?page=1&pageSize=20

Headers:

x-server-key: YOUR_SERVER_KEY

Query Parameters:

page (number, optional) - Page number, starts from 1
pageSize (number, optional) - Items per page, max 100
isActive (boolean, optional) - Filter by active status
accountType (string, optional) - Filter by account type: “master” or “sub”
address (string, optional) - Filter by wallet address (partial match)

Response:

{
  "users": [
    {
      "id": "user-123",
      "address": "0x742d35Cc6634C0532925a3b8D1B9d7c2bd34e8Dc",
      "accountType": "master",
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 150,
  "totalPages": 8
}

16. List Application Balances (Backend Only)

Returns a paginated list of all user balances for this application.

GET /api/v1/applications/balances?page=1&pageSize=20

Headers:

x-server-key: YOUR_SERVER_KEY

Query Parameters:

page (number, optional) - Page number, starts from 1
pageSize (number, optional) - Items per page, max 100
userId (string, optional) - Filter by user ID
token (string, optional) - Filter by token address

Response:

{
  "balances": [
    {
      "userId": "user-123",
      "address": "0x742d35Cc6634C0532925a3b8D1B9d7c2bd34e8Dc",
      "token": "0x23e459c24c4925ba89205c400dceca7abc11723d",
      "symbol": "USDC",
      "availableBalance": "1000.50",
      "lockedBalance": "50.25",
      "totalBalance": "1050.75"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 500,
  "totalPages": 25
}

17. List Application Orders (Backend Only)

Returns a paginated list of all orders for this application.

GET /api/v1/applications/orders?page=1&pageSize=20

Headers:

x-server-key: YOUR_SERVER_KEY

Query Parameters:

page (number, optional) - Page number, starts from 1; at most 10,000, the last page the listing counts towards
pageSize (number, optional) - Items per page, max 100
status (string, optional) - Filter by order status
tradingPairId (string, optional) - Filter by trading pair UUID
userId (string, optional) - Filter by user ID
side (string, optional) - Filter by order side: “BUY” or “SELL”
orderType (string, optional) - Filter by order type: “LIMIT” or “MARKET”

Response:

{
  "orders": [
    {
      "id": "ord_1234567890abcdef",
      "userId": "user-123",
      "tradingPairId": "123e4567-e89b-12d3-a456-426614174000",
      "orderType": "LIMIT",
      "side": "BUY",
      "price": "2000.50",
      "quantity": "1.5",
      "filledQuantity": "0.5",
      "status": "PARTIALLY_FILLED",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1000,
  "totalPages": 50
}

total and totalPages are exact up to 10,000 pages of the requested pageSize and saturate there (the last page the listing can reach), so an application with more matching orders than that reads the cap rather than its lifetime total.

18. List Application Movements (Backend Only)

Returns a paginated list of all ledger movements (deposits, withdrawals, trades, etc.) for this application.

GET /api/v1/applications/movements?page=1&pageSize=20

Headers:

x-server-key: YOUR_SERVER_KEY

Query Parameters:

page (number, optional) - Page number, starts from 1; at most 10,000, the last page the listing counts towards
pageSize (number, optional) - Items per page, max 100
userId (string, optional) - Filter by user ID
entryType (string, optional) - Filter by entry type
transactionType (string, optional) - Filter by transaction type
token (string, optional) - Filter by token address

Response:

{
  "movements": [
    {
      "id": "mov-123",
      "userId": "user-123",
      "amount": "100.50",
      "balanceBefore": "900.00",
      "balanceAfter": "1000.50",
      "entryType": "CREDIT",
      "transactionType": "DEPOSIT",
      "description": "USDC deposit",
      "token": "0x23e459c24c4925ba89205c400dceca7abc11723d",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 5000,
  "totalPages": 250
}

total and totalPages are exact up to 10,000 pages of the requested pageSize and saturate there (the last page the listing can reach), so an application with more matching movements than that reads the cap rather than its lifetime total.

19. Get Application Stats (Backend Only)

Returns aggregate volume and fee stats for this application. Stats are scoped to trades where the application’s users were the taker.

GET /api/v1/applications/stats

Headers:

x-server-key: YOUR_SERVER_KEY

Query Parameters:

since (string, optional) - Only include trades at or after this timestamp (ISO 8601)

Response:

{
  "volume": "12345.67",
  "makerFee": "12.34",
  "takerFee": "34.56",
  "applicationTakerFee": "5.67",
  "tradeCount": 42
}

volume (string) - Total quote volume (normalized) for trades where this application’s users were the taker
makerFee (string) - Total maker fees collected (normalized, quote token units)
takerFee (string) - Total taker fees collected (normalized, quote token units)
applicationTakerFee (string) - Application revenue share from taker fees (normalized, quote token units)
tradeCount (number) - Total number of trades

Withdrawal Endpoint

20. Initiate Withdrawal

Allocates a withdrawal and returns ready-to-submit vault calldata. The server signs the withdrawal with its WITHDRAWAL_SIGNER; you submit the returned calldata to the vault contract (tx.data) to move funds on-chain — no further server-side signing is needed. Requires the Withdraw permission on the session.

POST /api/v1/withdrawals

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE
Content-Type: application/json

Request Body:

{
  "assetId": "123e4567-e89b-12d3-a456-426614174000",
  "amount": "100500000",
  "destination": "0x742d35cc6634c0532925a3b8d1b9d7c2bd34e8dc"
}

Request Fields:

assetId (string, required) - Asset UUID to withdraw (get from a trading pair’s baseAssetId or quoteAssetId)
amount (string, required) - Raw token amount in the smallest unit as an integer string (e.g., "100500000" for 100.5 USDC with 6 decimals). Multiply the human-readable amount by 10**decimals.
destination (string, required) - 0x-prefixed 20-byte address that will receive the withdrawal

Response:

{
  "withdrawalIndex": 42,
  "vaultAddress": "0x6a86da986797d59a839d136db490292cd560c131",
  "calldata": "0x..."
}

Response Fields:

withdrawalIndex (number) - Allocated withdrawal index; matches executeSignedWithdrawal.index on-chain
vaultAddress (string) - 0x-prefixed lowercase vault contract address to send the calldata to (returned so you don’t have to query /applications/config separately)
calldata (string) - 0x-prefixed ABI-encoded calldata for executeSignedWithdrawal(...), already signed by the server. Submit it as tx.data to vaultAddress.

Look Up a Withdrawal

Fetch a previously-allocated withdrawal by index. Public lookup — no authentication required. Returns the same shape as the initiate response.

GET /api/v1/withdrawals/{withdrawalIndex}

Fee Simulation Endpoint

21. Simulate Order Fees

Simulates the fees for an order before placing it. Useful for displaying accurate fee estimates to users.

GET /api/v1/fees/simulate?tradingPairId={uuid}&side=BUY&price=40000&quantity=0.5

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE

Query Parameters:

tradingPairId (string, required) - Trading pair UUID
side (string, required) - Order side: “BUY” or “SELL”
price (string, required) - Price per unit
quantity (string, required) - Quantity to trade

Response:

{
  "notional": "20000.00",
  "monacoTakerFee": "20.00",
  "monacoMakerRebate": "-5.00",
  "applicationTakerFee": "10.00",
  "totalTakerFees": "30.00",
  "takerTotalPayment": "20030.00",
  "makerTotalReceipt": "19995.00",
  "buyOrderLockAmount": "20030.00",
  "monacoTakerFeeBpsExact": "6.5",
  "monacoMakerRebateBpsExact": "-1",
  "monacoTakerFeeBps": 10,
  "monacoMakerRebateBps": -2,
  "applicationTakerFeeBps": 5,
  "applicationName": "Monaco Trading Frontend"
}

Response Fields:

notional (string) - Total trade value (price × quantity)
monacoTakerFee (string) - Monaco protocol taker fee
monacoMakerRebate (string) - Monaco protocol maker rebate (negative = rebate)
applicationTakerFee (string) - Application-specific taker fee
totalTakerFees (string) - Total fees for taker orders (monaco + application)
takerTotalPayment (string) - Total amount taker pays (notional + fees)
makerTotalReceipt (string) - Total amount maker receives (notional + rebate)
buyOrderLockAmount (string, optional) - Amount to lock for BUY orders (null for SELL)
monacoTakerFeeBpsExact (string) - Tier-resolved Monaco taker rate as a decimal bps string (e.g. "6.5") — the exact rate the ledger charges this caller, equal to monacoTakerFee / notional
monacoMakerRebateBpsExact (string) - Tier-resolved Monaco maker rebate as a decimal bps string (negative = rebate, e.g. "-1")
monacoTakerFeeBps (number) - Deprecated. Whole-bps taker rate; an integer cannot carry fractional tiered rates, so it echoes the flat trading-pair column. Use monacoTakerFeeBpsExact or GET /api/v1/fees/tier
monacoMakerRebateBps (number) - Deprecated. Whole-bps maker rebate; same integer limitation. Use monacoMakerRebateBpsExact or GET /api/v1/fees/tier
applicationTakerFeeBps (number) - Application fee rate in basis points
applicationName (string, optional) - Application name

Trading Endpoints

All trading endpoints require a signed request — see Authenticating Requests.

22. Place Order

Creates a new limit or market order on the exchange. This endpoint handles both order types based on the orderType field.

POST /api/v1/orders

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE
Content-Type: application/json

Request Body (Limit Order):

{
  "tradingPairId": "123e4567-e89b-12d3-a456-426614174000",
  "orderType": "LIMIT",
  "side": "BUY",
  "price": "2000.50",
  "quantity": "1.5",
  "tradingMode": "SPOT",
  "expirationDate": "2024-12-31T23:59:59Z"
}

Note: expirationDate is an optional field for limit orders (default: 90 days for GTC orders). Request Body (Market Order):

{
  "tradingPairId": "123e4567-e89b-12d3-a456-426614174000",
  "orderType": "MARKET",
  "side": "SELL",
  "price": null,
  "quantity": "0.5",
  "tradingMode": "SPOT",
  "slippageToleranceBps": 100
}

Note: Market orders execute inside a mandatory 1,000 bps server-side price band. slippageToleranceBps is optional and only tightens that band (e.g., 100 = 1%); it cannot widen it. A market order may partially fill and cancel the remainder, or be rejected when no liquidity sits inside the band. Response:

{
  "orderId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "SUCCESS",
  "message": "Order processed with 2 trades",
  "matchResult": {
    "tradesCount": 2,
    "totalFilled": "0.2",
    "remainingQuantity": "0.3",
    "averageFillPrice": "35100.00",
    "status": "PARTIALLY_FILLED",
    "actualSlippageBps": 15,
    "maxSlippageBps": 50,
    "executionPriceRange": {
      "bestPrice": "35000.00",
      "worstPrice": "35150.00"
    }
  }
}

Request Fields:

tradingPairId (string, required) - Trading pair UUID (get from /api/v1/market/pairs)
orderType (string, required) - “LIMIT” or “MARKET”
side (string, required) - “BUY” or “SELL”
quantity (string, required) - Order quantity as decimal string
price (string, optional) - Order price (required for LIMIT orders, ignored for MARKET)
tradingMode (string, optional) - Trading mode: “SPOT” (default) or “MARGIN”
timeInForce (string, optional) - “GTC” (default), “IOC”, or “FOK”
expirationDate (string, optional) - Custom expiration in ISO 8601 format (default: 90 days for GTC)
slippageToleranceBps (number, optional) - For market orders: tightens the mandatory 1,000 bps price band, in basis points (e.g., 100 = 1%). Cannot widen the band
useMasterBalance (boolean, optional) - For sub-accounts: use master account’s balance

Response Fields:

orderId (string) - Unique order identifier (UUID)
status (string) - “SUCCESS” or “FAILED”
message (string) - Operation message
matchResult (object, optional) - Immediate execution results if order matched:
- tradesCount (number) - Number of trades executed
- totalFilled (string) - Total quantity filled
- remainingQuantity (string) - Remaining unfilled quantity
- averageFillPrice (string, optional) - Average fill price across all trades
- status (string) - Order status after matching (e.g., “SUBMITTED”, “PARTIALLY_FILLED”, “FILLED”)
- actualSlippageBps (number, optional) - Actual slippage in basis points (positive = worse price)
- maxSlippageBps (number, optional) - Maximum slippage allowed when order was submitted
- executionPriceRange (object, optional) - Price range: bestPrice, worstPrice

23. Cancel Order

Cancels an existing open order by its ID.

POST /api/v1/orders/cancel

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE
Content-Type: application/json

Request Body:

{
  "orderId": "123e4567-e89b-12d3-a456-426614174000"
}

Response:

{
  "orderId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "SUCCESS",
  "message": "Order cancelled successfully"
}

Request Fields:

orderId (string) - ID of the order to cancel

Response Fields:

orderId (string) - ID of the cancelled order
status (string) - “SUCCESS” or “FAILED”
message (string) - Response message

Error Responses:

400 Bad Request - Invalid order ID, order already filled/cancelled/expired, or order not found
401 Unauthorized - Authentication required or order doesn’t belong to user
500 Internal Server Error - Server error during cancellation

24. Batch Cancel Orders

Cancels multiple orders in a single request (best-effort per order). Supports canceling specific orders or all active orders for the user.

POST /api/v1/orders/batch-cancel?cancel_all=false

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE
Content-Type: application/json

Query Parameters:

cancel_all (boolean, optional) - If true, cancels all active orders for the user (ignores orderIds in body). Default: false

Request Body (when cancel_all=false):

{
  "orderIds": [
    "123e4567-e89b-12d3-a456-426614174000",
    "987e6543-e21b-12d3-a456-426614174001"
  ]
}

Request Body (when cancel_all=true):

{
  "orderIds": []
}

Response:

{
  "success": true,
  "totalRequested": 3,
  "totalCancelled": 2,
  "totalFailed": 1,
  "results": [
    {
      "orderId": "123e4567-e89b-12d3-a456-426614174000",
      "success": true,
      "cancelledAt": "2024-01-15T10:35:00Z",
      "error": null
    },
    {
      "orderId": "987e6543-e21b-12d3-a456-426614174001",
      "success": false,
      "cancelledAt": null,
      "error": {
        "code": "ORDER_NOT_FOUND",
        "message": "Order not found or already cancelled"
      }
    }
  ]
}

Response Fields:

success (boolean) - True if all orders cancelled successfully
totalRequested (number) - Number of orders requested to cancel
totalCancelled (number) - Number successfully cancelled
totalFailed (number) - Number that failed to cancel
results (array) - Per-order results:
- orderId (string) - Order ID
- success (boolean) - Whether this specific order was cancelled
- cancelledAt (string, optional) - Cancellation timestamp (ISO 8601, UTC)
- error (object, optional) - Error details if failed (code, message)

Error Responses:

400 Bad Request - No order IDs provided when cancel_all is false, or invalid order IDs
401 Unauthorized - Authentication required
500 Internal Server Error - Server error during cancellation

Note: This is a best-effort operation. Some cancellations may fail while others succeed; failures don’t roll back successful cancellations.

25. Replace Order

Replaces an existing order by canceling it and creating a new order atomically. Returns a new order ID.

PUT /api/v1/orders/{orderId}

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE
Content-Type: application/json

Request Body:

{
  "price": "2100.00",
  "quantity": "2.0"
}

Response:

{
  "orderId": "987e6543-e21b-12d3-a456-426614174000",
  "status": "SUCCESS",
  "message": "Order replaced successfully",
  "updatedFields": {
    "price": "2100.00",
    "quantity": "2.0"
  },
  "originalOrderId": "123e4567-e89b-12d3-a456-426614174000",
  "matchResult": null
}

Request Fields:

price (string, optional) - New order price (omit to keep original price)
quantity (string, optional) - New order quantity (omit to keep remaining quantity)

Response Fields:

orderId (string) - New order ID after replacement
status (string) - “SUCCESS” or “FAILED”
message (string) - Operation message
updatedFields (object) - Fields that were updated
originalOrderId (string) - Original order ID that was replaced
matchResult (object, nullable) - Match result if order executed immediately

26. Get Orders

Retrieves a paginated list of orders for the authenticated user with optional filtering. Every kind of order comes back in one stream sorted by timestamp — book orders, TWAP parents and conditional orders — so there is no separate open-orders endpoint: filter status to SUBMITTED,PARTIALLY_FILLED for the working set across all three kinds. orderType names each row’s kind, and a TWAP parent or conditional order carries its full detail under twap or conditional respectively.

GET /api/v1/orders?page=1&pageSize=20&status=FILLED,PARTIALLY_FILLED&tradingPairId=123e4567-e89b-12d3-a456-426614174000

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE

Query Parameters:

page (number, optional) - Page number, starts from 1 (default: 1)
pageSize (number, optional) - Items per page (default: 20); max 100 in page-number mode, up to 1000 when pageToken is present
status (string, optional) - Filter by order status. Supports comma-separated list for multiple statuses (e.g., “FILLED,PARTIALLY_FILLED”). Valid values: “SUBMITTED”, “PARTIALLY_FILLED”, “FILLED”, “SETTLED”, “CANCELLED”, “EXPIRED”, “REJECTED”
tradingPairId (string, optional) - Filter by trading pair UUID
pageToken (string, optional) - Cursor for cursor-mode pagination, which merges hot and archived rows. Send an empty string to start a walk over full history, then send each response’s nextPageToken to continue; the walk is exhausted when a page returns no rows and an empty nextPageToken. Cursor mode ignores page (it comes back as 0), but total / totalPages ARE populated — bounded by a server count ceiling (exact up to it, then reported as the ceiling with totalCapped: true; see the response below)

Response:

{
  "orders": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "tradingPairId": "456e7890-e12b-12d3-a456-426614174000",
      "orderType": "LIMIT",
      "side": "BUY",
      "price": "2000.50",
      "quantity": "1.5",
      "filledQuantity": "0.5",
      "averageFillPrice": "2000.45",
      "status": "PARTIALLY_FILLED",
      "tradingMode": "SPOT",
      "timeInForce": "GTC",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:35:00Z",
      "expirationDate": "2024-04-15T10:30:00Z"
    }
  ],
  "total": 45,
  "page": 1,
  "pageSize": 20,
  "totalPages": 3,
  "totalCapped": false
}

Order Fields:

id (string) - Order unique identifier (UUID)
tradingPairId (string) - Trading pair ID (UUID)
orderType (string) - What kind of order this row is: “LIMIT” or “MARKET” for a book order, “TWAP” for a TWAP parent, “CONDITIONAL” for a price-triggered order. “TWAP” and “CONDITIONAL” appear only in responses — order creation still takes “LIMIT” or “MARKET”
twap (object, optional) - Present only when orderType is “TWAP”: the full TWAP parent, identical to what GET /api/v1/orders/twap/{twapOrderId} returns
conditional (object, optional) - Present only when orderType is “CONDITIONAL”: the full conditional order, identical to what the conditional-order endpoints return
conditionalOrderId (string, optional) - Present only on an order the engine placed for a take-profit or stop-loss trigger: the conditional order that fired it. Absent on orders the client placed, on TWAP slice children, and on triggered closes written before the field existed (there is no backfill). Served by this endpoint and GET /api/v1/orders/{orderId}; no WebSocket frame carries it
side (string) - “BUY” or “SELL”
price (string, optional) - Order price (null for market orders)
quantity (string) - Order quantity
filledQuantity (string) - Quantity filled so far
averageFillPrice (string, optional) - Average fill price (null if not filled yet)
status (string) - Order status (see Order Status enum)
tradingMode (string) - “SPOT” or “MARGIN”
timeInForce (string, optional) - “GTC”, “IOC”, or “FOK”
createdAt (string) - Order creation timestamp (ISO 8601, UTC)
updatedAt (string, optional) - Last update timestamp (ISO 8601, UTC)
expirationDate (string, optional) - Order expiration date
applicationTakerFee (string, optional) - Application taker fee amount
monacoTakerFee (string, optional) - Monaco protocol taker fee amount
monacoMakerRebate (string, optional) - Monaco protocol maker rebate amount
totalTakerFees (string, optional) - Total taker fees (monaco + application)
takerTotalPayment (string, optional) - Total amount taker paid
makerTotalReceipt (string, optional) - Total amount maker received

27. Get Order by ID

Retrieves detailed information about a specific order by its ID.

GET /api/v1/orders/{orderId}

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE

Path Parameters:

orderId (string) - Order UUID

Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "tradingPairId": "456e7890-e12b-12d3-a456-426614174000",
  "orderType": "LIMIT",
  "side": "BUY",
  "price": "2000.50",
  "quantity": "1.5",
  "filledQuantity": "1.5",
  "averageFillPrice": "2000.45",
  "status": "FILLED",
  "tradingMode": "SPOT",
  "timeInForce": "GTC",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:35:00Z",
  "expirationDate": "2024-04-15T10:30:00Z"
}

Error Responses:

401 Unauthorized - Authentication required
403 Forbidden - Order doesn’t belong to user
404 Not Found - Order not found

Market Data Endpoints

Public endpoints for accessing trading pairs and market data. Authentication is not required.

28. Get Trading Pairs

Retrieves a paginated list of all available trading pairs with optional filtering.

GET /api/v1/market/pairs?page=1&pageSize=20&marketType=SPOT&isActive=true

Query Parameters:

page (number, optional) - Page number, starts from 1 (default: 1)
pageSize (number, optional) - Items per page, max 100 (default: 20)
marketType (string, optional) - Filter by market type: “SPOT”
baseToken (string, optional) - Filter by base token symbol (e.g., “ETH”)
quoteToken (string, optional) - Filter by quote token symbol (e.g., “USD”)
isActive (boolean, optional) - Filter by active status. An operator-managed market is public only while its launch’s durable runtime projection reads live — not merely its launch phase — so a pending, warming or halted managed launch is hidden and isActive=false does not surface it. A pair with no managed launch keeps its ordinary visibility.

Response:

{
  "tradingPairs": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "symbol": "ETH/USDC",
      "baseToken": "ETH",
      "baseAssetName": "Ethereum",
      "quoteToken": "USDC",
      "quoteAssetName": "USDC",
      "baseTokenContract": "0x...",
      "quoteTokenContract": "0x...",
      "baseAssetId": "123e4567-e89b-12d3-a456-426614174001",
      "quoteAssetId": "123e4567-e89b-12d3-a456-426614174002",
      "baseDecimals": 18,
      "quoteDecimals": 6,
      "baseIconUrl": "https://assets.monaco.xyz/tokens/eth.svg",
      "quoteIconUrl": "https://assets.monaco.xyz/tokens/usdc.svg",
      "minOrderSize": "0.01",
      "maxOrderSize": "1000.0",
      "tickSize": "0.01",
      "makerFeeBps": -1,
      "takerFeeBps": 5,
      "marketType": "SPOT",
      "isActive": true
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 15,
  "totalPages": 1
}

Fields:

id (string) - Trading pair UUID (use as tradingPairId in order requests)
symbol (string) - Trading pair symbol (e.g., “ETH/USDC”)
baseToken (string) - Base token symbol
baseAssetName (string) - Human-readable base asset display name (e.g., “Robinhood Markets” for HOOD) — useful for matching markets by company/asset name in search
quoteToken (string) - Quote token symbol
quoteAssetName (string) - Human-readable quote asset display name
baseTokenContract (string) - Base token contract address
quoteTokenContract (string) - Quote token contract address
baseAssetId (string) - Base asset UUID (use for withdrawal requests)
quoteAssetId (string) - Quote asset UUID (use for withdrawal requests)
baseDecimals (number) - Base token decimals
quoteDecimals (number) - Quote token decimals
baseIconUrl (string) - Base token icon URL
quoteIconUrl (string) - Quote token icon URL
minOrderSize (string) - Minimum order size
maxOrderSize (string) - Maximum order size
tickSize (string) - Minimum price increment
makerFeeBps (number) - Deprecated. Flat pair-level maker fee in basis points (negative = rebate); this is not the per-user tiered rate. Use GET /api/v1/fees/tier for the caller’s real rate
takerFeeBps (number) - Deprecated. Flat pair-level taker fee in basis points; this is not the per-user tiered rate. Use GET /api/v1/fees/tier for the caller’s real rate
marketType (string) - “SPOT” or “MARGIN”
isActive (boolean) - Whether pair is active for trading

29. Get Trading Pair by ID

Retrieves detailed information about a specific trading pair by its UUID.

GET /api/v1/market/pairs/{pair_id}

Path Parameters:

tradingPairId (string) - Trading pair UUID (e.g., “123e4567-e89b-12d3-a456-426614174000”)

Response:

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "symbol": "ETH/USDC",
    "baseToken": "ETH",
    "quoteToken": "USDC",
    "baseTokenContract": "0x...",
    "quoteTokenContract": "0x...",
    "baseAssetId": "123e4567-e89b-12d3-a456-426614174001",
    "quoteAssetId": "123e4567-e89b-12d3-a456-426614174002",
    "baseDecimals": 18,
    "quoteDecimals": 6,
    "minOrderSize": "0.01",
    "maxOrderSize": "1000.0",
    "tickSize": "0.01",
    "makerFeeBps": -1,
    "takerFeeBps": 5,
    "marketType": "SPOT",
    "isActive": true
  }
}

Error Responses:

404 Not Found - Trading pair not found

30. Get Market Metadata

Retrieves current price, 24-hour statistics, and market information for a trading pair.

GET /api/v1/market/pairs/{pair_id}/metadata

Path Parameters:

tradingPairId (string) - Trading pair UUID

Response:

{
  "symbol": "BTC/USDC",
  "baseIconUrl": "https://assets.monaco.xyz/tokens/btc.svg",
  "quoteIconUrl": "https://assets.monaco.xyz/tokens/usdc.svg",
  "lastPrice": "95432.50",
  "lastPriceTimestamp": 1736742000000,
  "high24h": "96500.00",
  "low24h": "94200.00",
  "volume24h": "1234.5678",
  "priceChange24h": "1232.50",
  "priceChangePercent24h": "1.31",
  "marketInitializationTimestamp": 1735000000000
}

Response Fields:

symbol (string) - Trading pair symbol (e.g., “BTC/USDC”)
baseIconUrl (string) - Base token icon URL
quoteIconUrl (string) - Quote token icon URL
lastPrice (string, optional) - Current price from latest candle (null if no data)
lastPriceTimestamp (number, optional) - Timestamp of last price in milliseconds (null if no data)
high24h (string, optional) - 24-hour high price (null if less than 24h of data)
low24h (string, optional) - 24-hour low price (null if less than 24h of data)
volume24h (string, optional) - 24-hour trading volume in base asset (null if less than 24h of data)
quoteVolume24h (string, optional) - 24-hour trading volume in quote token / USDC (null if less than 24h of data)
priceChange24h (string, optional) - Price change in last 24 hours (null if less than 24h of data)
priceChangePercent24h (string, optional) - Percentage change in last 24 hours (null if less than 24h of data)
marketInitializationTimestamp (number, optional) - Timestamp when market first started trading (first candle)

Error Responses:

404 Not Found - Trading pair not found or inactive
500 Internal Server Error - Failed to fetch market data

31. Get Historical Candlestick Data

Retrieves historical OHLCV (Open, High, Low, Close, Volume) candlestick data for a trading pair.

GET /api/v1/market/pairs/charts/candlestick/{tradingPairId}/{interval}?startTime=1704067200000&endTime=1704153600000&limit=350

Path Parameters:

tradingPairId (string) - Trading pair UUID (get from /api/v1/market/pairs)
interval (string) - Candlestick interval: “1m”, “5m”, “15m”, “1h”, “4h”, or “1d”

Query Parameters:

startTime (number, optional) - Start timestamp in Unix milliseconds (for forward pagination)
endTime (number, optional) - End timestamp in Unix milliseconds (for backward pagination)
limit (number, optional) - Maximum candlesticks to return (default: 350, max: 500)

Response:

{
  "data": [
    {
      "T": 1704067200000,
      "t": 1704067260000,
      "o": "2250.50",
      "h": "2255.00",
      "l": "2248.00",
      "c": "2252.75",
      "v": "125.5",
      "s": "ETH",
      "i": "1m",
      "n": 45
    }
  ]
}

Candlestick Fields:

T (number) - Candle start timestamp (Unix milliseconds)
t (number) - Candle end timestamp (Unix milliseconds)
o (string) - Open price
h (string) - High price
l (string) - Low price
c (string) - Close price
v (string) - Volume (base token)
s (string) - Symbol
i (string) - Interval
n (number) - Number of trades in this candle

Supported Intervals:

1m - 1 minute
5m - 5 minutes
15m - 15 minutes
1h - 1 hour
4h - 4 hours
1d - 1 day

Error Responses:

400 Bad Request - Invalid interval or time range
404 Not Found - Trading pair not found or inactive

Orderbook Endpoints

32. Get Orderbook Snapshot

Gets the complete orderbook snapshot for a trading pair showing all bids and asks with their price levels. This is a public endpoint that does not require authentication.

GET /api/v1/orderbook/{tradingPairId}?levels=20&tradingMode=Spot&magnitude=0.01&denomination=base

Path Parameters:

tradingPairId (string) - Trading pair UUID

Query Parameters:

levels (number, optional) - Number of price levels to return, max 100 (default: all levels)
tradingMode (string, optional) - Trading mode: “Spot” or “Margin” (default: “Spot”)
magnitude (string, optional) - Price grouping magnitude for aggregation. Valid values: “0.0001”, “0.001”, “0.01”, “0.1”, “1”, “10”, “100”, “1000”, “10000”. If not specified, returns ungrouped levels
denomination (string, optional) - Quantity denomination: “base” (default) or “quote”. When “quote”, quantities are multiplied by price

Response:

{
  "eventType": "orderbook_snapshot",
  "tradingPairId": "00000000-0000-0000-0000-000000000001",
  "pair": "BTC/USDC",
  "tradingMode": "Spot",
  "timestamp": "2024-01-15T10:30:00Z",
  "sequenceNumber": 12345,
  "baseToken": "BTC",
  "quoteToken": "USDC",
  "baseDecimals": 8,
  "quoteDecimals": 6,
  "data": {
    "bids": [
      {"price": "34900.00", "quantity": "1.2", "orderCount": 2}
    ],
    "asks": [
      {"price": "35100.00", "quantity": "0.8", "orderCount": 1}
    ],
    "bestBid": "34900.00",
    "bestAsk": "35100.00",
    "bidVolume": "15.5",
    "askVolume": "12.3",
    "priceChange": null
  }
}

Response Fields:

eventType (string) - Event type (“orderbook_snapshot” for HTTP)
tradingPairId (string) - Trading pair UUID
pair (string) - Trading pair symbol (e.g., “BTC/USDC”)
tradingMode (string) - “Spot” or “Margin”
timestamp (string) - Snapshot timestamp (ISO 8601, UTC)
sequenceNumber (number) - Sequence number for ordering updates
baseToken (string) - Base token symbol
quoteToken (string) - Quote token symbol
baseDecimals (number) - Base token decimals
quoteDecimals (number) - Quote token decimals
data (object) - Orderbook data:
- bids (array) - Buy orders sorted by price (highest first)
- asks (array) - Sell orders sorted by price (lowest first)
- bestBid (string) - Current best bid price
- bestAsk (string) - Current best ask price
- bidVolume (string) - Total bid volume
- askVolume (string) - Total ask volume
- priceChange (object, optional) - Price change information

Error Responses:

400 Bad Request - Invalid magnitude or denomination value
404 Not Found - Trading pair not found
500 Internal Server Error - Matching engine not initialized

Delegated Agents Endpoints

Delegated agents let a master account authorize an external agent wallet to trade on its behalf under a fine-grained policy. The owner registers an agent and policy; the agent then authenticates with its own session key and exchanges it for an owner-scoped delegated session. The management endpoints require a signed request — see Authenticating Requests.

33. Upsert Delegated Agent

Registers or updates a delegated agent. Master accounts only. The delegation is keyed on agentAddress, so calling again with the same address updates the existing delegation and its policy.

POST /api/v1/delegated-agents

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE
Content-Type: application/json

Request Body:

{
  "agentAddress": "0x742d35cc6634c0532925a3b8d4060f31e2c3d8b5",
  "name": "market-maker-bot",
  "expiresAt": "2026-12-31T23:59:59Z",
  "allowedActions": ["CREATE_ORDER", "CANCEL_ORDER"],
  "allowedTradingPairIds": [],
  "allowedMarginAccountIds": [],
  "allowedOrderTypes": ["LIMIT"],
  "allowedTimeInForce": ["GTC"],
  "maxLeverage": "10",
  "maxOrderNotional": "50000",
  "maxOpenOrders": 100
}

Request Fields:

agentAddress (string, required) - Agent wallet address (EVM, 42 chars including 0x)
name (string, optional) - Human-friendly label for the agent
expiresAt (string, optional) - Delegation expiry timestamp (ISO 8601). Omit for no expiry
allowedActions (array, optional) - Actions the agent may perform: CREATE_ORDER, CANCEL_ORDER, REPLACE_ORDER
allowedTradingPairIds (array, optional) - Trading pair UUIDs the agent may trade. An order is allowed if its market or its margin account is permitted
allowedMarginAccountIds (array, optional) - Margin account UUIDs the agent may trade against. An order is allowed if its market or its margin account is permitted
allowedOrderTypes (array, optional) - Permitted order types (LIMIT, MARKET). Empty means unrestricted
allowedTimeInForce (array, optional) - Permitted time-in-force values (GTC, IOC, FOK). Empty means unrestricted
maxLeverage (string, optional) - Maximum leverage the agent may use (decimal string). Omit for no limit
maxOrderNotional (string, optional) - Maximum order notional (price × quantity, decimal string). Omit for no limit
maxOpenOrders (number, optional) - Maximum concurrent open orders. Omit for no limit

Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "ownerUserId": "456e7890-e12b-12d3-a456-426614174001",
  "agentAddress": "0x742d35cc6634c0532925a3b8d4060f31e2c3d8b5",
  "name": "market-maker-bot",
  "isActive": true,
  "expiresAt": "2026-12-31T23:59:59Z",
  "revokedAt": null,
  "allowedActions": ["CREATE_ORDER", "CANCEL_ORDER"],
  "allowedTradingPairIds": [],
  "allowedMarginAccountIds": [],
  "allowedOrderTypes": ["LIMIT"],
  "allowedTimeInForce": ["GTC"],
  "maxLeverage": "10",
  "maxOrderNotional": "50000",
  "maxOpenOrders": 100
}

Response Fields:

id (string) - Delegation UUID
ownerUserId (string) - Owner account UUID the agent acts on behalf of
agentAddress (string) - Agent wallet address (EVM)
name (string, optional) - Human-friendly label for the agent
isActive (boolean) - Whether the delegation is active
expiresAt (string, optional) - Delegation expiry timestamp (ISO 8601), if set
revokedAt (string, optional) - Revocation timestamp (ISO 8601), if revoked
allowedActions, allowedTradingPairIds, allowedMarginAccountIds, allowedOrderTypes, allowedTimeInForce (arrays) - The policy as stored
maxLeverage, maxOrderNotional (string, optional) / maxOpenOrders (number, optional) - Policy limits, if set

Error Responses:

401 Unauthorized - Authentication required
403 Forbidden - Only master accounts can manage delegated agents

34. List Delegated Agents

Lists every agent the calling account owns, each with its policy. Master accounts only.

GET /api/v1/delegated-agents

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE

Response:

{
  "agents": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "ownerUserId": "456e7890-e12b-12d3-a456-426614174001",
      "agentAddress": "0x742d35cc6634c0532925a3b8d4060f31e2c3d8b5",
      "name": "market-maker-bot",
      "isActive": true,
      "expiresAt": "2026-12-31T23:59:59Z",
      "revokedAt": null,
      "allowedActions": ["CREATE_ORDER", "CANCEL_ORDER"],
      "allowedTradingPairIds": [],
      "allowedMarginAccountIds": [],
      "allowedOrderTypes": ["LIMIT"],
      "allowedTimeInForce": ["GTC"],
      "maxLeverage": "10",
      "maxOrderNotional": "50000",
      "maxOpenOrders": 100
    }
  ]
}

Response Fields:

agents (array) - The calling owner’s delegated agents (each object as in Upsert Delegated Agent)

Error Responses:

401 Unauthorized - Authentication required
403 Forbidden - Only master accounts can list delegated agents

35. List Delegating Owners

Reverse lookup keyed on the caller’s own wallet address: an agent that has authenticated with its own session key discovers which owners it may act on behalf of, and the ownerUserId to pass to Create Delegated Session. Returns only active (non-revoked, non-expired) delegations.

GET /api/v1/delegated-agents/owners

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE

Response:

{
  "owners": [
    {
      "ownerUserId": "123e4567-e89b-12d3-a456-426614174000",
      "delegationId": "456e7890-e12b-12d3-a456-426614174001",
      "name": "market-maker-bot",
      "isActive": true,
      "expiresAt": "2026-12-31T23:59:59Z"
    }
  ]
}

Response Fields:

owners (array) - Owners that have an active delegation to the calling agent:
- ownerUserId (string) - Owner account UUID to pass to Create Delegated Session
- delegationId (string) - Delegation UUID for the (owner, agent) pair
- name (string, optional) - Human-friendly label the owner gave this agent, if any
- isActive (boolean) - Whether the delegation is active
- expiresAt (string, optional) - Delegation expiry timestamp (ISO 8601), if set

Error Responses:

401 Unauthorized - Authentication required

36. Revoke Delegated Agent

Revokes the delegation identified by delegatedAgentId. Master accounts only. Existing delegated sessions are not invalidated; only future session creation is blocked.

DELETE /api/v1/delegated-agents/{delegatedAgentId}

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE

Path Parameters:

delegatedAgentId (string) - Delegation UUID to revoke

Response:

{
  "status": "REVOKED"
}

Error Responses:

400 Bad Request - Invalid delegatedAgentId
401 Unauthorized - Authentication required
403 Forbidden - Only master accounts can revoke delegated agents
404 Not Found - Delegated agent not found

37. Create Delegated Session

Exchanges the agent’s own session for an owner-scoped delegated session. The agent authenticates with its own session key, then calls this with the ownerUserId it wants to act for (discover it via List Delegating Owners) and a freshly generated session public key. The new session acts as the owner but records the agent’s address for policy enforcement. Requires an active delegation for the (owner, agent) pair.

POST /api/v1/delegated-agents/sessions

Headers:

X-Monaco-PublicKey: YOUR_SESSION_PUBLIC_KEY
X-Monaco-Timestamp: UNIX_MILLISECONDS
X-Monaco-Signature: ED25519_SIGNATURE
Content-Type: application/json

Request Body:

{
  "ownerUserId": "123e4567-e89b-12d3-a456-426614174000",
  "sessionPublicKey": "3b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29"
}

Request Fields:

ownerUserId (string, required) - Owner account UUID to act on behalf of (discover via List Delegating Owners)
sessionPublicKey (string, required) - 64-char lowercase-hex ed25519 public key the agent generated for this delegated session. Subsequent requests acting on the owner’s behalf are signed with the matching private key

Response:

{
  "expiresAt": 1735689599,
  "delegationId": "456e7890-e12b-12d3-a456-426614174001",
  "ownerUserId": "123e4567-e89b-12d3-a456-426614174000",
  "agentAddress": "0x742d35cc6634c0532925a3b8d4060f31e2c3d8b5"
}

Response Fields:

expiresAt (number) - Session expiry as a Unix timestamp (seconds)
delegationId (string) - Delegation UUID for the active (owner, agent) pair
ownerUserId (string) - Owner account UUID the session acts on behalf of
agentAddress (string) - Agent wallet address recorded on the session for policy enforcement

Error Responses:

400 Bad Request - Invalid request
401 Unauthorized - Authentication required
403 Forbidden - No active delegation for owner

Error Handling

All endpoints return standard HTTP status codes:

200 - Success
400 - Bad Request (invalid parameters)
401 - Unauthorized (missing, invalid, or expired session signature)
403 - Forbidden (authenticated, but not allowed to access the resource)
500 - Internal Server Error

Error Response Format:

{
  "error": "Authentication failed",
  "message": "Invalid signature provided"
}

When a rejection originates in the matching engine, the envelope additionally carries a stable machine-readable code (for example POST_ONLY_WOULD_CROSS for a post-only order that would cross the book). The field is omitted entirely when no engine code applies — match on code when present instead of parsing message:

{
  "error": "BAD_REQUEST",
  "message": "Bad request: post-only order would cross: 550e8400-e29b-41d4-a716-446655440000",
  "code": "POST_ONLY_WOULD_CROSS",
  "statusCode": 400
}

Handling Session Expiry (401 Errors)

When a session expires or is revoked, authenticated endpoints return 401 Unauthorized. Re-run the challenge/verify flow to start a new session. A clock more than 30 seconds out of sync with the server also produces 401 — keep the request timestamp accurate. The TypeScript SDK corrects for this itself, from each response’s Date header; a raw client should do the same or keep its clock synced.

Code Examples

cURL

Complete Authentication Flow:

# 0. Generate an ed25519 session keypair locally (implementation varies)

# 1. Create challenge — pass the session public key
curl -X POST https://staging.apimonaco.xyz/api/v1/auth/challenge \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0x742d35Cc6634C0532925a3b8D4060f31E2C3d8B5",
    "clientId": "688a21440e304c06b935f743dae88278",
    "sessionPublicKey": "3b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29"
  }'

# 2. Sign the returned message with your wallet (implementation varies)

# 3. Verify signature — registers the session public key, opens a session
curl -X POST https://staging.apimonaco.xyz/api/v1/auth/verify \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0x742d35Cc6634C0532925a3b8D4060f31E2C3d8B5",
    "signature": "0x1234567890abcdef...",
    "nonce": "abc123def456",
    "clientId": "688a21440e304c06b935f743dae88278",
    "sessionPublicKey": "3b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29"
  }'

# 4. Sign every subsequent request with the session private key
#    (see #authenticating-requests)

JavaScript (Node.js)

const { bytesToHex, utf8ToBytes } = require('@noble/hashes/utils');
const { sha256 } = require('@noble/hashes/sha256');
const ed = require('@noble/ed25519');

class MonacoAPI {
  constructor(baseUrl) {
    this.baseUrl = baseUrl;
    this.session = null; // { publicKey, privateKey } as hex
  }

  // Generate the ed25519 session keypair (hex-encoded)
  static generateSession() {
    const privateKey = ed.utils.randomPrivateKey();
    return {
      privateKey: bytesToHex(privateKey),
      publicKey: bytesToHex(ed.getPublicKey(privateKey)),
    };
  }

  async createChallenge(address, sessionPublicKey, clientId = null) {
    const payload = { address, sessionPublicKey: sessionPublicKey };
    if (clientId) payload.clientId = clientId;

    const response = await fetch(`${this.baseUrl}/api/v1/auth/challenge`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload),
    });
    if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    return response.json();
  }

  // After the wallet signs the challenge message, register the session
  async verifySignature(address, signature, nonce, session, clientId = null) {
    const payload = {
      address,
      signature,
      nonce,
      sessionPublicKey: session.publicKey,
    };
    if (clientId) payload.clientId = clientId;

    const response = await fetch(`${this.baseUrl}/api/v1/auth/verify`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload),
    });
    if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);

    this.session = session; // sign all later requests with this keypair
    return response.json();
  }

  // Build the X-Monaco-* signing headers for an authenticated request
  signedHeaders(method, pathWithQuery, body = '') {
    const timestampMs = Date.now();
    const bodyHash = bytesToHex(sha256(body ? utf8ToBytes(body) : new Uint8Array(0)));
    const signingString = `${method}\n${pathWithQuery}\n${timestampMs}\n${bodyHash}`;
    const signature = bytesToHex(ed.sign(utf8ToBytes(signingString), this.session.privateKey));
    return {
      'X-Monaco-PublicKey': this.session.publicKey,
      'X-Monaco-Timestamp': String(timestampMs),
      'X-Monaco-Signature': signature,
    };
  }

  // Example authenticated GET
  async getBalances() {
    const path = '/api/v1/accounts/balances';
    const response = await fetch(`${this.baseUrl}${path}`, {
      headers: this.signedHeaders('GET', path),
    });
    if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    return response.json();
  }
}

Getting Credentials

Frontend Applications

Contact the Monaco Protocol team to obtain your clientId for frontend authentication.

Backend Services

Contact the Monaco Protocol team to obtain your secretKey for backend authentication.

Migration from SDK

If you’re migrating from the TypeScript SDK, note these key differences:

Field Names: API uses snake_case (e.g., clientId) while SDK uses camelCase (e.g., clientId)
Manual Request Signing: You must generate a session keypair and sign every request with it (no token to store)
Wallet Signing: You must implement wallet message signing separately
Error Handling: Parse HTTP status codes instead of SDK error classes

Withdrawal Usage Examples

These examples assume the MonacoAPI class above (with signedHeaders()) and an authenticated api whose api.session is set. The session must hold the Withdraw permission. Deposits are on-chain: send tokens directly to the vault contract and the indexer credits your balance — there is no deposit API. Withdrawals go through the API below, which returns signed vault calldata for you to submit on-chain.

JavaScript Example

async function initiateWithdrawal(api, assetId, amountRaw, destination) {
  const path = '/api/v1/withdrawals';
  const body = JSON.stringify({ assetId: assetId, amount: amountRaw, destination });

  const response = await fetch(`${api.baseUrl}${path}`, {
    method: 'POST',
    headers: {
      ...api.signedHeaders('POST', path, body),
      'Content-Type': 'application/json',
    },
    body,
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  return response.json();
}

// Usage - For 100.5 USDC (6 decimals): 100.5 * 10**6 = 100500000
const withdrawal = await initiateWithdrawal(
  api,
  '123e4567-e89b-12d3-a456-426614174000', // Asset UUID from trading pair
  '100500000',                             // Raw format: 100.5 USDC with 6 decimals
  '0x742d35cc6634c0532925a3b8d1b9d7c2bd34e8dc' // Destination address
);

console.log(`Withdrawal index: ${withdrawal.withdrawalIndex}`);
// Submit the signed calldata to the vault contract to complete the withdrawal on-chain:
//   await walletClient.sendTransaction({ to: withdrawal.vaultAddress, data: withdrawal.calldata });

Trading Usage Examples

JavaScript Example

async function placeOrder(api, order) {
  const path = '/api/v1/orders';
  const body = JSON.stringify(order);
  const response = await fetch(`${api.baseUrl}${path}`, {
    method: 'POST',
    headers: {
      ...api.signedHeaders('POST', path, body),
      'Content-Type': 'application/json',
    },
    body,
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  return response.json();
}

async function replaceOrder(api, orderId, updates) {
  const path = `/api/v1/orders/${orderId}`;
  const body = JSON.stringify(updates);
  const response = await fetch(`${api.baseUrl}${path}`, {
    method: 'PUT',
    headers: {
      ...api.signedHeaders('PUT', path, body),
      'Content-Type': 'application/json',
    },
    body,
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  return response.json();
}

// Usage - tradingPairId is a UUID from /api/v1/market/pairs
const tradingPairId = '123e4567-e89b-12d3-a456-426614174000';

const limitOrder = await placeOrder(api, {
  tradingPairId: tradingPairId,
  orderType: 'LIMIT',
  side: 'BUY',
  price: '2000.50',
  quantity: '1.5',
  tradingMode: 'SPOT',
});
console.log(`Limit Order ID: ${limitOrder.orderId}`);

const marketOrder = await placeOrder(api, {
  tradingPairId: tradingPairId,
  orderType: 'MARKET',
  side: 'SELL',
  price: null,
  quantity: '0.5',
  tradingMode: 'SPOT',
  slippageToleranceBps: 100, // optional: 1% max slippage
});
console.log(`Market Order ID: ${marketOrder.orderId}`);

const replaceResult = await replaceOrder(api, limitOrder.orderId, {
  price: '1950.00',
  quantity: '1.5',
});
console.log(`New Order ID: ${replaceResult.orderId}`);
console.log(`Original Order ID: ${replaceResult.originalOrderId}`);

Security Considerations

Store Secret Keys Securely - Never expose backend secret keys in client-side code
Handle Session Expiry - Detect 401 responses and re-run the challenge/verify flow
Validate Responses - Always validate API responses before using data
Use HTTPS - All API requests must use HTTPS in production
Revoke Sessions - Implement logout by calling POST /api/v1/auth/revoke, and never persist the session private key insecurely

​Endpoint

​Base URLs

​Request Requirements

​Routes

​OpenAPI

​Authentication Flow

​Authenticating Requests

​Network Configuration

​Enum Value Formats

​Market Types & Trading Modes

​Order Types

​Order Sides

​Order Status

​Authentication Endpoints

​1. Create Authentication Challenge

​2. Verify Signature

​3. Refresh Session

​4. Revoke Session

​Account Endpoints

​5. Get User Profile

​6. Get User Balances

​7. Get User Balance by Asset

​8. Get User Movements

​9. List Sub-Accounts with Balances

​Sub-Account Limits Endpoints

​10. Create Sub-Account Limit

​11. Get Sub-Account Limits

​12. Update Sub-Account Limit

​13. Delete Sub-Account Limit

​Application Configuration Endpoint

​14. Get Application Configuration

​Application Backend Endpoints

​Backend Authentication Header

​15. List Application Users (Backend Only)

​16. List Application Balances (Backend Only)

​17. List Application Orders (Backend Only)

​18. List Application Movements (Backend Only)

​19. Get Application Stats (Backend Only)

​Withdrawal Endpoint

​20. Initiate Withdrawal

​Look Up a Withdrawal

​Fee Simulation Endpoint

​21. Simulate Order Fees

​Trading Endpoints

​22. Place Order

​23. Cancel Order

​24. Batch Cancel Orders

​25. Replace Order

​26. Get Orders

​27. Get Order by ID

​Market Data Endpoints

​28. Get Trading Pairs

​29. Get Trading Pair by ID

​30. Get Market Metadata

​31. Get Historical Candlestick Data

​Orderbook Endpoints

​32. Get Orderbook Snapshot

​Delegated Agents Endpoints

​33. Upsert Delegated Agent

​34. List Delegated Agents

​35. List Delegating Owners

​36. Revoke Delegated Agent

​37. Create Delegated Session

​Error Handling

​Handling Session Expiry (401 Errors)

​Code Examples

​cURL

​JavaScript (Node.js)

​Getting Credentials

​Frontend Applications

​Backend Services

​Migration from SDK

​Withdrawal Usage Examples

​JavaScript Example

​Trading Usage Examples

​JavaScript Example

​Security Considerations

Endpoint

Base URLs

Request Requirements

Routes

OpenAPI

Authentication Flow

Authenticating Requests

Network Configuration

Enum Value Formats

Market Types & Trading Modes

Order Types

Order Sides

Order Status

Authentication Endpoints

1. Create Authentication Challenge

2. Verify Signature

3. Refresh Session

4. Revoke Session

Account Endpoints

5. Get User Profile

6. Get User Balances

7. Get User Balance by Asset

8. Get User Movements

9. List Sub-Accounts with Balances

Sub-Account Limits Endpoints

10. Create Sub-Account Limit

11. Get Sub-Account Limits

12. Update Sub-Account Limit

13. Delete Sub-Account Limit

Application Configuration Endpoint

14. Get Application Configuration

Application Backend Endpoints

Backend Authentication Header

15. List Application Users (Backend Only)

16. List Application Balances (Backend Only)

17. List Application Orders (Backend Only)

18. List Application Movements (Backend Only)

19. Get Application Stats (Backend Only)

Withdrawal Endpoint

20. Initiate Withdrawal

Look Up a Withdrawal

Fee Simulation Endpoint

21. Simulate Order Fees

Trading Endpoints

22. Place Order

23. Cancel Order

24. Batch Cancel Orders

25. Replace Order

26. Get Orders

27. Get Order by ID

Market Data Endpoints

28. Get Trading Pairs

29. Get Trading Pair by ID

30. Get Market Metadata

31. Get Historical Candlestick Data

Orderbook Endpoints

32. Get Orderbook Snapshot

Delegated Agents Endpoints

33. Upsert Delegated Agent

34. List Delegated Agents

35. List Delegating Owners

36. Revoke Delegated Agent

37. Create Delegated Session

Error Handling

Handling Session Expiry (401 Errors)

Code Examples

cURL

JavaScript (Node.js)

Getting Credentials

Frontend Applications

Backend Services

Migration from SDK

Withdrawal Usage Examples

JavaScript Example

Trading Usage Examples

JavaScript Example

Security Considerations