{
  data: {
    address: string;   // Your Lethean wallet address
    alias: string;     // Display alias
    message: string;   // The random message that was signed
    signature: string; // Wallet signature of the message
  };
  neverExpires: boolean; // Whether the session should persist indefinitely
}

To obtain data, sign a message using the Lethean wallet RPC with a random string.

Response

{
  success: boolean;
  data?: string; // Error message on failure
}

On success, the response includes a session token used for all authenticated endpoints below.

Create New Order

Post a new buy or sell order to the order book.

Method: POST
Path: /api/orders/create

Request

{
  token: string; // Authentication token
  orderData: {
    type: "buy" | "sell";
    side: "limit";       // Order type (limit orders only)
    price: string;       // Price per unit in base currency
    amount: string;      // Quantity of the asset to trade
    pairId: number;      // Trading pair ID
  };
}

Response

{
  success: boolean;
  data?: string | {
    hasNotification: boolean;
    id: number;
    type: string;
    timestamp: string;
    side: string;
    price: string;
    amount: string;
    total: string;
    pair_id: number;
    user_id: number;
    status: string;
    left: string;       // Remaining unfilled amount
    updatedAt: string;
    createdAt: string;
  };
}

Get Active Orders

Retrieve your active orders and any matching tips for a given trading pair.

Method: POST
Path: /api/orders/get-user-page

Request

{
  token: string;   // Authentication token
  pairId: number;  // Trading pair ID
}

Response

{
  success: boolean;
  data: {
    orders: {
      id: number;
      type: string;
      timestamp: string;
      side: string;
      price: string;
      amount: string;
      total: string;
      pair_id: number;
      user_id: number;
      status: string;
      left: string;
      hasNotification: boolean;
      createdAt: string;
      updatedAt: string;
      isInstant: boolean;     // Whether the counterparty bot is active
    }[];

    applyTips: {
      id: number;
      left: string;
      price: string;
      user: {
        alias: string;
        address: string;
        createdAt: string;
        updatedAt: string;
      };
      type: string;
      total: string;
      connected_order_id: number;
      transaction: boolean;       // false = you can apply; true = use Confirm Transaction
      hex_raw_proposal: string;
      isInstant: boolean;
    }[];
  };
}

The applyTips array contains matched orders from other users. Check the transaction field:

false -- The other party has not yet applied. You can apply using the Apply for Matched Order endpoint.
true -- The other party has already applied. You are the finaliser and should use the Confirm Transaction endpoint.

Apply for Matched Order

Submit an ionic swap proposal to match against an existing order. Use this when the transaction field in applyTips is false.

Method: POST
Path: /api/orders/apply-order

Request

{
  token: string; // Authentication token
  orderData: {
    id: string;                  // Your order ID
    connected_order_id: string;  // The counterparty order ID
    hex_raw_proposal: string;    // Ionic swap proposal hex
  };
}

To obtain hex_raw_proposal, generate an ionic swap proposal via the Lethean wallet RPC API. This is a hex-encoded proposal containing a half-created transaction template and the data required by the counterparty to finalise and sign the transaction, encrypted with a common shared key.

Response

{
  success: boolean;
  data?: string; // Error message on failure
}

Confirm Transaction

Confirm that you have finalised an ionic swap transaction (or a partial fill). Use the Get Active Transactions endpoint first to obtain the transaction ID.

Method: POST
Path: /api/transactions/confirm

Request

{
  token: string;          // Authentication token
  transactionId: number;  // Transaction ID from get-active-tx-by-orders-ids
}

Response

{
  success: boolean;
  data?: string; // Error message on failure
}

Delete (Cancel) Order

Cancel one of your open orders.

Method: POST
Path: /api/orders/cancel

Request

{
  token: string;    // Authentication token
  orderId: number;  // The order ID to cancel
}

Response

{
  success: boolean;
  data?: string; // Error message on failure
}

Get DEX Trading Pair

Retrieve detailed information about a specific trading pair, including both currencies and market data.

Method: POST
Path: /api/dex/get-pair

Request

{
  id: number; // Trading pair ID
}

Response

{
  success: boolean;
  data: {
    id: number;
    first_currency_id: number;
    second_currency_id: number;
    rate: number;
    coefficient: number;
    high: number;
    low: number;
    volume: number;
    featured: boolean;
    createdAt: string;
    updatedAt: string;
    first_currency: {
      id: number;
      name: string;
      code: string;
      type: string;
      asset_id: string;
      auto_parsed: boolean;
      asset_info: {
        id: string;
        logo: string;
        price: number | null;
        ticker: string;
        asset_id: string;
        full_name: string;
        meta_info: string;
        price_url: string;
        decimal_point: number;
        current_supply: string;
        total_max_supply: string;
      };
      whitelisted: boolean;
      createdAt: string;
      updatedAt: string;
    };
    second_currency: {
      id: number;
      name: string;
      code: string;
      type: string;
      asset_id: string;
      auto_parsed: boolean;
      asset_info: {
        decimal_point: number;
      };
      whitelisted: boolean;
      createdAt: string;
      updatedAt: string;
    };
  };
}

Get Active Transactions

Retrieve an active transaction by matching two order IDs. Use this to check whether the counterparty has confirmed and to obtain the proposal hex for finalisation.

Method: POST
Path: /api/transactions/get-active-tx-by-orders-ids

Request

{
  token: string;          // Authentication token
  firstOrderId: number;   // One of the matched order IDs
  secondOrderId: number;  // The other matched order ID
}

Response

{
  success: boolean;
  data?: {
    buy_order_id: number;
    sell_order_id: number;
    amount: string;
    timestamp: number;
    status: string;
    creator: string;
    hex_raw_proposal: string;
  } | string; // Error message on failure
}

Ping Activity Checker

Signal that your bot is active and ready to accept orders instantly. Call this every 10 seconds to keep the "instant" icon visible on your orders, so other users know your bot will respond immediately.

Method: POST
Path: /api/dex/renew-bot

Request

{
  token: string;    // Authentication token
  orderId: number;  // The order to mark as instant
}

Response

{
  success: boolean;
  data?: string; // Error message on failure
}

Bot Trading Flow

A typical automated trading bot follows this sequence:

Authenticate -- Sign a message with your wallet and call /api/auth to get a session token.
Get trading pairs -- Call /api/dex/get-pair to find the pair you want to trade.
Create order -- Post a buy or sell order via /api/orders/create.
Ping -- Call /api/dex/renew-bot every 10 seconds to show instant availability.
Poll for matches -- Call /api/orders/get-user-page to check for applyTips.
Apply or confirm -- Depending on the transaction field:
- If false: generate an ionic swap proposal and call /api/orders/apply-order.
- If true: get the transaction via /api/transactions/get-active-tx-by-orders-ids, finalise locally, then call /api/transactions/confirm.
Clean up -- Cancel unfilled orders with /api/orders/cancel when done.