Filament API

This is an in-depth guide to onboarding market makers, focusing on how orders are processed and signed.

We will explain how to use the provided code, break down key concepts such as signature generation, and guide you through the modules used (e.g., nanoid, ethers).

Our platform interacts with the order book API to facilitate trading using buy and sell orders based on price changes.

Dependencies

  • nanoid: Generates unique, secure IDs used for each order.

  • ethers.js (version 5.7.2): A library that provides utilities for interacting with Ethereum, particularly useful for signing messages (orders in our case).

Key Concepts and Workflow

1. Price Change Orders

Market makers often need to update their orders based on price changes. The processOrders function automates this by creating and sending orders to the platform with unique identifiers and signatures.

import { nanoid } from "nanoid";
import { handleOrderSignature } from "./utils";
export NEXT_API_URL=https://orderbook.filament.finance/sei;

  • nanoid: This package is used to create a unique identifier for each order. Each generated ID is lowercase to maintain consistency.

  • handleOrderSignature: This utility function is used to sign the order ID using the provided private key.

2. Signature Generation: handleOrderSignature

The function handleOrderSignature is critical for ensuring the authenticity of each order by creating a cryptographic signature.

Explanation:

  • orderId: The unique order ID generated by nanoid.

  • signature: The private key used to sign the order (passed as signingKey in processOrders).

  • The function uses ethers.js to sign the message, ensuring that only the owner of the private key can create valid orders.

Purpose of Signature:

  • Signatures verify the identity of the market maker submitting the order. When an order is signed with the private key, the platform can trust the authenticity of the request, making it difficult for malicious actors to forge orders.

3. Function: processOrders

The processOrders function handles the creation of orders and prepares them to be sent to the API.

Explanation of Parameters:

  • price: Price to place orders

  • isBuy: A boolean value indicating whether the order is a buy (true) or a sell (false).

  • asset: The asset or token being traded (e.g., SOL, BTC).

  • account: The wallet address of the market maker, which will be used for the order.

  • signingKey: The private key used to sign the order for verification purposes.

Workflow:

  1. For each price change, it generates a unique order ID using nanoid().

  2. The order ID is signed using the handleOrderSignature function.

  3. An order payload is created with information like the asset being traded, order size, leverage, and limit price.

  4. The payload can be sent to the API for order execution.

4. Sending the Order

Once the payload is created, it can be sent to the platform’s API at the endpoint provided in the configuration. The API will process the order and execute it according to the details provided (e.g., size, limit price, etc.).

  • NEXT_API_URL: This is the base URL for the order book API, which will receive the payload containing the order details.

Exchange URL

Limit Order Payload:

Market Order Payload

Cancel Order

Add Collateral

Remove Collateral

Update Take Profit On Position

Update Stop Loss on Position

Update Take Profit And Stop Loss on Position

GET Endpoints

Get All Traded Assets:

Relevant Info:

  1. Current mark Price

  2. Current Spot Price

  3. Index Token Address for Asset

Response:

GET Calls for Orders, Positions And Market Stats

Please find the below Postman Documentation of GET endpoints, to get following info:

  1. Open Orders

    1. {{baseUrl}}/v1/orders/open-orders/paginated/account/:account?token=&side=&page=0&size=10

      This end-point provides details on all open orders placed by the user.

      It is paginated endpoint.

      Inputs:

      account: Account address need to be passed in lower case (Mandatory)

      Optional arguments to filter out futher:

      1. token: Asset Eg: BTC

      2. side: BUY/SELL

      Output:

      Paginated response of user open orders:

      Datapoints include:

      1. orderId: Unique Order id of the order.

      2. openTime: order open time

      3. account: user account

      4. side: BUY/SELL

      5. token: asset on which position is created

      6. triggerPrice: price at which order will be triggered.

      7. typeOfOrder:

        1. Limit

        2. Market

        3. TakeProfit

        4. StopLoss

      8. size: Size of order in USDC.

      9. orderValue: Number of tokens.

      10. collateral: Used collateral for this open order.

      11. decreaseOrder: true if order a decrease order

        1. Note: Order can be of two types,

          1. Normal orders to increase or create positon.

          2. Orders to reduce position are categorized as decrease orders.

      12. isTakeProfit -> true is order is a Take Profit order, otherwise false

      13. isStopLoss -> true is order is a Stop Loss order, otherwise false

      14. decreaseOrder -> Provides current liquidation price of user position, it keep on updating with moving market price.

      Eg:

  2. Closed Orders

    1. {{baseUrl}}/v1/orders/closed-orders/paginated/account/:account?token=&side=&page=0&size=10

      This end-point provides details on all closed orders by the user.

      It is paginated endpoint.

      Inputs:

      account: Account address need to be passed in lower case (Mandatory)

      Optional arguments to filter out futher:

      1. token: Asset Eg: BTC

      2. side: BUY/SELL

      Output:

      Paginated response of user open orders:

      Datapoints include:

      1. orderId: Unique Order id of the order.

      2. openTime: order open time

      3. closedTime: Give last update on this order

      4. account: user account

      5. side: BUY/SELL

      6. token: asset on which position is created

      7. triggerPrice: price at which order will be triggered.

      8. typeOfOrder:

        1. Limit

        2. Market

        3. TakeProfit

        4. StopLoss

      9. size: Size of order in USDC.

      10. orderValue: Number of tokens.

      11. orderStatus:

        1. OPEN

        2. MATCHED

        3. CANCELLED

        4. FAILED

      12. collateral: Used collateral for this order.

      13. decreaseOrder: true if order a decrease order

        1. Note: Order can be of two types,

          1. Normal orders to increase or create positon.

          2. Orders to reduce position are categorized as decrease orders.

      14. isTakeProfit -> true is order is a Take Profit order, otherwise false

      15. isStopLoss -> true is order is a Stop Loss order, otherwise false

      16. decreaseOrder -> Provides current liquidation price of user position, it keep on updating with moving market price.

      Eg:

      JSON

      Note: There can be multiple enteries for an orderId.

      Eg: Lets say for orderId: "edfd8saq8b8ajwzlakdza"

      1. Order opened at time: 30/09/2024 - 11:56:47, for size: 400 USDC

      2. It Matched for size $200, then an entry will be present with status matched and size $200.

      3. Then if this order is cancelled, then another entry will be present of size $200 with status CANCELLED

  3. Positons (Open Positions - Trades)

    1. URL: {{baseUrl}}/v1/positions/trades/paginated/:account?page=0&size=10

      This end-point provides details on all open positions of the user.

      Inputs:

      account: Account address need to be passed in lower case.

      Output:

      Paginated response of user positions:

      Datapoints include:

      1. openTime: Position open time

      2. account: user account

      3. side: BUY/SELL

      4. token: asset on which position is created

      5. entryPrice: average price of your position.

      6. markPrice: current mark price, which is basically the best Ask.

      7. size: Size of position in USDC, it keep on updating with market price movement.

      8. quantity: Number of tokens (remains constant unless position is increased or decreased)

      9. Collateral: Amount locked in USDC

      10. Fees: Borrowing fees + Trading fees + Funding fees

      11. realizedPnL: This is actually unrealized PnL value. which is calculated basd on formula.

        1. BUY -> (markPrice - averagePrice) x quantity

        2. SELL -> (averagePrice - markPrice) x quantity

      12. takeProfit -> Return take profit price if set for position, otherwise null.

      13. stopLoss -> Return stop loss price if set for position, otherwise null.

      14. Liquidation Price -> Provides current liquidation price of user position, it keep on updating with moving market price.

      15. leverage → size / collateral

      Eg:

  4. Trade History

    1. URL: {{baseUrl}}/v1/positions/tradeHistory/paginated/:account?page=0&size=10

      This end-point provides all matched trades, it gives insight on every order match.

      Inputs:

      account: Account address need to be passed in lower case.

      Output:

      Paginated response of user positions:

      Datapoints include:

      1. tradeTime: Time when trade occurrred.

      2. account: user account

      3. side: BUY/SELL

      4. token: asset on which position is created

      5. price: price at which order was matched and trade was executed.

      6. size: Size of position in USDC.

      7. tradeValue: Number of tokens

      8. Collateral: Amount locked in USDC

      9. Fees: Borrowing fees + Trading fees + Funding fees charged

      10. closedPnL: Realized PnL

      11. orderType ->

        1. OpenLong

        2. OpenShort

        3. CloseLong

        4. CloseShort

        5. LiquidationCloseLong

        6. LiquidationCloseShort

      12. associatedOrderId: Order Id associated with this trade.

      Eg:

    2. Get trade history with associated Order Id.

      1. URL: {{baseUrl}}/v1/positions/tradeHistory/paginated/:account?page=0&size=10&associatedOrderId=

      2. Inputs:

        1. account: Account address need to be passed in lower case.

        2. associatedOrderId (Optional parameter): Order Id, for which necessary trades are required to be found.

      3. Output:

        1. Example

  5. Account Balance

    1. URL: {{baseUrl}}/v1/accountData/balance/:account

      This endpoint give insight on available deposited balance in USDC. Basically amount of collateral free to use. Input: account: User address Output: USDC value Eg: 343.917502459535209000

    2. URL: {{baseUrl}}/v1/positions/balance/:account

      It gives insight on USDC locked with the position, adding or subtracting unrealized PnL and subtracting fees.

      Input:

      account: user account

      Output:

      Gives you list of objects, each object corresponds to position of every asset.

      token -> Asset info

      amount -> collateral locked in position + open orders for this asset + unrealized PnL (can be positive or negative)

      value → Number of BTC tokens (locked in position + tokens that will be obtained on fulfilling open orders)

      Eg:

  6. Account PnL and Volume

  7. Latest status on orders based on order Id

    1. POST call on URL: {{baseUrl}}/v1/orders/latest-status

    2. BODY: List of order ids 1.

    3. Response: 1.

Pre-requisite

Bearer Token need to be passed as the method of authentication to fetch data from the following endpoints.

How to fetch bearer token is explained above.

PostMan Collection

Web Socket Connections

API_BASE_URL = https://orderbook.filament.finance/sei/

Order Book State:

  1. To get Order Book State, we can use the following end points:

    1. Get Index Token, from “Get All Traded Assets endpoint” for each traded asset. For eg: for BTC, indexToken = “0x152b9d0fdc40c096757f570a51e494bd4b943e50”

    2. complete URL = ${API_BASE_URL}api/order-book/orderbook-websocket;

    3. To connect with websockets, we need to create a initial connection, then connect to /topic/orderBookState:

  2. It will return following JSON

    PAYLOAD

Live Feed On Assets:

  1. To get live feed on state, we can use the following end points:

    1. complete URL = ${API_BASE_URL}api/order-book/orderbook-websocket;

    2. Get Index Token, from “Get All Traded Assets endpoint” for each traded asset. For eg: for BTC, indexToken = “0x152b9d0fdc40c096757f570a51e494bd4b943e50”

    3. To connect with web sockets, we need to create a initial connection, then connect to /topic/livefeed:

  2. It will return following JSON

Native WebSocket Connections

Native WebSocket connections provide a more granular approach to interacting with WebSocket servers without relying on higher-level libraries like SockJS or STOMP clients. Below is an example of connecting to the Filament Finance Order Book WebSocket server using Python.

WebSocket Connection Workflow

  1. Establish a WebSocket Connection

    • Connect to the WebSocket endpoint using the websocket.WebSocketApp library.

    • Define callback functions to handle on_open, on_message, on_close, and on_error events.

  2. Send STOMP Frames

    • Connect Frame: Establishes the STOMP connection by sending necessary headers.

    • Subscribe Frame: Subscribes to the desired topic, such as /topic/orderBookState.

    • Send Frame: Sends initialization messages with the required payload (e.g., indexToken).

  3. Receive and Process Messages

    • Handle incoming messages via the on_message callback to process data in real-time.

  4. Threaded Connection

    • Run the WebSocket client in a separate thread to maintain a persistent connection while allowing other processes to run concurrently.

OrderBook State:

BASE_URL = wss://orderbook.filament.finance/sei/api/order-book/book-websocket

Example Code

Order Updates:

BASE_URL = wss://orderbook.filament.finance/sei/api/order-websocket

account → Wallet address need to passed in lower case Eg: 0xb02a810c5bb22b093ed52e3d6adb45c8519d68e7

Mandatory Parameters:

  1. account

Optional Parameters:

  1. token

  2. side

Payload required to be passed:

Example Code

Sample Response, on order updates:

How to Place Close Orders for Open Positions

Using the response from the trades endpoint, you can determine the necessary details (quantity, entryPrice, and side) for each position and decide the price at which they want to close the position, either for profit or loss. Below is a step-by-step guide:

Step 1: Fetch Open Positions

  1. Endpoint:

    https://orderbook.filament.finance/sei/api/v1/positions/trades/paginated/{ACCOUNT}?page={page}&size={size}

  2. Data Retrieved:

    Each position includes fields like:

    • Side (BUY or SELL)

    • Quantity (e.g., 0.000139)

    • Entry Price (e.g., 98269.916666)

    • Collateral and other metrics.

    Example, for account:

  3. Use these fields:

    • quantity: Total amount of the token to close.

    • entryPrice: Reference price to determine profit/loss.

    • side: Indicates whether the position is BUY or SELL.

Step 2: Place Close Order

  1. Endpoint:

    https://orderbook.filament.finance/sei/filament/api/v1/exchange

  2. Payload Construction:

    • Construct the payload using the provided quantity, closePrice (user-defined), and side.

    • reduceOnly flag should be true for closed orders.

    • size = quantity x entryPrice

    • isBuy

      • false: If position was short

      • true: If position was long

  3. Payload Example: For a SELL position:

  4. Parameters Explained:

    • isBuy: false for closing a SELL position; true for closing a BUY position.

    • size: Equal to the quantity from the position.

    • reduceOnly: Ensures the order reduces the position.

    • limitPrice: User-specified close price.

  5. Send the Request:

    • Use POST to send the constructed payload to the endpoint.

Step 3: Confirmation

  • The response from the order placement endpoint will indicate whether the close order was successfully placed.

Summary

  1. Fetch open positions using the trades endpoint.

  2. Extract quantity, entryPrice, and side from the response.

  3. Define a close price → Which will decide whether position will be closed in profit or loss.

  4. Construct a reduce-only order payload:

    • Use isBuy based on the position side (BUY or SELL).

    • Set reduceOnly to true.

    • Specify thelimitPrice.

  5. Place the close order via the orderbook endpoint.

PreviousSecurity Audits

Last updated