lthn/trade-backend
6
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
Page: API
Pages
API Configuration Home Setup Trade API Reference User Guides
1 API
Claude edited this page 2026-04-03 11:12:45 +01:00
Table of Contents

API Reference

All endpoints are mounted under the /api prefix. Admin endpoints use /api/admin.

Authenticated endpoints require a token field in the JSON request body containing a valid JWT. Tokens are obtained via the authentication flow.

All responses follow the shape { success: boolean, data: ... }.

Authentication

Wallet-based authentication using a challenge-response signature scheme.

POST /api/auth/request-auth

Request a challenge message for wallet signature verification.

Body:

{
  "address": "iTHN...",
  "alias": "my-username"
}
  • address -- Lethean wallet address (must start with iTHN)
  • alias -- User display name

Response:

{
  "success": true,
  "data": "uuid-challenge-message"
}

POST /api/auth

Submit a signed challenge to receive a JWT.

Body:

{
  "data": {
    "address": "iTHN...",
    "alias": "my-username",
    "signature": "...",
    "message": "uuid-challenge-message"
  },
  "neverExpires": false
}

Response:

{
  "success": true,
  "data": "jwt-token-string"
}

Tokens expire after 24 hours by default. Set neverExpires: true for a persistent token.

POST /api/check-auth

Verify a token is still valid. Requires authentication.

Body: { "token": "..." }

Response: { "success": true, "userData": { ... } }

DEX / Trading Pairs

POST /api/dex/get-pairs-page

Retrieve a paginated list of trading pairs.

Body:

{
  "page": 1,
  "searchText": "",
  "whitelistedOnly": false,
  "sortOption": "VOLUME_HIGH_TO_LOW"
}

POST /api/dex/get-pairs-pages-amount

Get the total number of pages for a given search query.

Body:

{
  "searchText": "",
  "whitelistedOnly": false
}

POST /api/dex/get-pair

Get details for a single trading pair.

Body: { "id": 1 }

POST /api/dex/find-pair

Find a pair ID by the two asset IDs.

Body:

{
  "first": "asset-id-hex...",
  "second": "asset-id-hex..."
}

POST /api/dex/get-assets-price-rates

Get current price rates for a list of assets.

Body:

{
  "assetsIds": ["asset-id-1", "asset-id-2"]
}

Response:

{
  "success": true,
  "priceRates": [
    {
      "asset_id": "...",
      "rate": 0.5,
      "day_change": -2.1,
      "day_volume": 1000,
      "day_high": 0.55,
      "day_low": 0.48,
      "last_transaction_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

POST /api/dex/volume-stats

Get trade volume statistics for a user on a specific pair.

Body:

{
  "address": "iTHN...",
  "pairID": 1,
  "from": 1700000000000,
  "to": 1700100000000
}

POST /api/dex/renew-bot

Renew a market-making bot's expiration. Requires authentication.

Body: { "token": "...", "orderId": 123 }

Orders

POST /api/orders/create

Create a new buy or sell order. Requires authentication.

Body: Validated via createOrderValidator -- includes pair ID, side, price, and amount.

POST /api/orders/get-page

Get a paginated list of orders for a pair (public).

POST /api/orders/get-user-page

Get paginated orders for the authenticated user. Requires authentication.

PATCH /api/orders/get

Get the authenticated user's orders for a specific pair. Requires authentication.

POST /api/orders/cancel

Cancel an order. Requires authentication.

PATCH /api/orders/cancel-all

Cancel all of the authenticated user's orders. Requires authentication.

POST /api/orders/apply-order

Apply (fill) an existing order. Requires authentication.

POST /api/orders/get-candles

Get candlestick chart data for a pair.

POST /api/orders/get-chart-orders

Get orders formatted for chart display.

POST /api/orders/get-pair-stats

Get 24h statistics for a trading pair.

POST /api/orders/get-trades

Get recent trades for a pair.

PATCH /api/orders/get-user-orders-pairs

Get the authenticated user's orders across all pairs. Requires authentication.

Transactions

All transaction endpoints require authentication.

POST /api/transactions/confirm

Confirm (settle) a pending transaction.

POST /api/transactions/cancel

Cancel a pending transaction.

POST /api/transactions/get-active-tx-by-orders-ids

Get active transactions for a list of order IDs.

POST /api/transactions/get-my-transactions

Get the authenticated user's transaction history.

POST /api/transactions/get-my-pending

Get the authenticated user's pending transactions.

P2P Offers

POST /api/offers/get-page

Get a paginated list of P2P offers (public).

POST /api/offers/update

Update an existing offer. Requires authentication.

POST /api/offers/delete

Delete an offer. Requires authentication.

GET /api/offers/get-stats

Get aggregate offer statistics (public).

Chats

All chat endpoints require authentication.

POST /api/chats/create

Create a new chat for a P2P trade.

POST /api/chats/get-chat

Get a specific chat by ID.

POST /api/chats/get-chat-chunk

Get a chunk (page) of messages from a chat.

POST /api/chats/get-all-chats

Get all chats for the authenticated user.

POST /api/chats/delete-chat

Delete a chat.

User

All user endpoints require authentication.

POST /api/user/get-user

Get the authenticated user's profile.

POST /api/user/get-notifications-amount

Get the count of unread notifications.

POST /api/user/set-favourite-currencies

Set the user's favourite currencies list.

Body: { "token": "...", "currencies": [...] }

Configuration

GET /api/config

Get the list of all registered currencies/assets. Public, no authentication required.

Response:

{
  "success": true,
  "data": {
    "currencies": [
      {
        "id": 1,
        "name": "LTHN",
        "code": "lethean",
        "type": "crypto",
        "asset_id": "d632...",
        "whitelisted": true,
        "asset_info": { "decimal_point": 12, "full_name": "Lethean", "ticker": "LTHN" }
      }
    ]
  }
}

Statistics

GET /api/stats/asset

Get statistics for a single asset.

Query parameters:

  • asset_id -- the asset's hex ID
  • from_timestamp (optional) -- period start (ms epoch)
  • to_timestamp (optional) -- period end (ms epoch)

Response includes: current TVL, price, 24h change, volume, market cap, supply, and period data if timestamps are provided.

GET /api/stats/total

Get aggregate statistics across all active pairs.

Query parameters:

  • from_timestamp (optional) -- period start (ms epoch)
  • to_timestamp (optional) -- period end (ms epoch)

Response includes: total TVL, largest TVL asset, and period data (active tokens, most traded, total volume).

GET /api/stats/total_stats_in_period

Get total TVL and volume for a specific time range.

Query parameters (required):

  • from_timestamp -- period start (ms epoch)
  • to_timestamp -- period end (ms epoch)

Admin

All admin endpoints require authentication and admin privileges. Mounted at /api/admin.

POST /api/admin/check-admin

Verify the current user has admin access.

POST /api/admin/get-admins

List all admin users.

POST /api/admin/add-admin

Grant admin to a user. Body: { "alias": "username" }

POST /api/admin/delete-admin

Revoke admin from a user. Body: { "id": 123 }

POST /api/admin/get-featured

Get all featured trading pairs.

POST /api/admin/add-featured

Feature a trading pair. Body: { "asset_id": "hex..." }

POST /api/admin/delete-featured

Remove a pair from featured. Body: { "id": 1 }

POST /api/admin/get_order_data

Inspect an order's full data. Body: { "orderId": 123 }

POST /api/admin/get_user_data

Inspect a user's full data. Body: { "userId": 123 }

WebSocket Events

The backend uses Socket.IO for real-time updates. Clients connect to the same host/port as the REST API.

Client-to-Server

Event Data Description
in-account { id } Join user notification room
in-trading { id } Subscribe to pair order updates
out-trading { id } Unsubscribe from pair updates
in-dex-notifications { userData } Subscribe to DEX notifications (auth required)
out-dex-notifications { userData } Unsubscribe from DEX notifications (auth required)
join { chat_id, ... } Join a chat room
leave -- Leave all chat rooms
create-message { chat_id, text, ... } Send a chat message
change-deposit { chat_id, ... } Update deposit state
submit-watched { chat_id, ... } Mark messages as read

Server-to-Client

Event Data Description
new-order { orderData } New order placed on subscribed pair
delete-order { orderId } Order removed from subscribed pair
update-orders -- Order book changed, refresh needed
update-pair-stats { pairStats } Pair statistics updated
new-message { message, ... } New chat message in joined chat
check-connection -- Connection health check
refresh-request -- Notification that requires UI refresh
order-notification { orderData } Personal order status update
order-notification-cancelation { orderId } Personal order cancelled

Rate Limiting

The API enforces a global rate limit of 6000 requests per 10-minute window per IP address. Exceeding this returns:

{
  "success": false,
  "data": "Too many requests from this IP, please try again later."
}