### Install exchange-bot-sdk dependency

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Install the @evedex/exchange-bot-sdk package via npm. This is the first step after initializing an npm project.

```bash
npm i @evedex/exchange-bot-sdk --save
```

--------------------------------

### Install ws package for Node.js

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Install the 'ws' package to provide a WebSocket implementation for Node.js environments, required for initializing the container.

```bash
npm i ws --save
```

--------------------------------

### Configuration JSON Example

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

A sample JSON configuration structure for defining buy and sell power settings.

```json
{
  "buy": {
    "power": 1000
  },
  "sell": {
    "power": 2000
  }
}
```

--------------------------------

### Initialize Balance and Listen

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Demonstrates how to initialize the container, access a wallet account, and start listening for balance updates.

```typescript
import { WebSocket } from "ws";
import { Environment, Container } from "@evedex/exchange-bot-sdk";

const config = {
  environment: Environment.DEV,
  centrifugeWebSocket: WebSocket,
  wallets: {
    myWallet: {
      privateKey: "your-private-key",
    },
  },
  apiKeys: {
    mainApiKey: {
      apiKey: "your-api-key",
    },
  },
};

const devContainer = new Container(config);

const walletAccount = await devContainer.account("myWallet");

const balance = walletAccount.getBalance();

await balance.listen();
```

--------------------------------

### Perform HTTP GET request for documentation query

Source: https://docs.evedex.com/glossary.md

Use this HTTP GET request format to query the documentation. Replace <question> with your specific inquiry and <endgoal> with your broader objective.

```http
GET https://docs.evedex.com/glossary.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### Create SIWE Message and Signature for Authorization

Source: https://docs.evedex.com/developers/developers/authorization.md

Example of creating the SIWE message and signature for authorization. It fetches a nonce from GET /auth/nonce, builds the message, signs it with the user's wallet, and sends it to POST /auth/user/sign-up to receive a JWT token. Throws 'Invalid auth' if the response status is 400 or higher.

```typescript
function createSiweMessage(
  { address, uri, version, chainId, nonce, issuedAt }: {address: string, uri: string, version: string, chainId: number, nonce: string, issuedAt: string}
) {
  return `${uri} wants you to sign in with your Ethereum account:
${address}


URI: ${uri}
Version: ${version}
Chain ID: ${chainId}
Nonce: ${nonce}
Issued At: ${issuedAt}`;
}

const signer = await ethers.getSigner();
const message = `EVEDEX sign in`;
const address = await signer.getAddress();

const nonceRes = await fetch(`https://auth.evedex.com/auth/nonce`, {
  method: 'GET',
  headers: { accept: 'application/json' },
});
const { nonce } = await nonceRes.json();

const siweMessage = createSiweMessage({
  address: address,
  statement: `Sign in to https://exchange.evedex.com`,
  uri: 'https://exchange.evedex.com',
  version: '1',
  chainId: await signer.provider.getNetwork().then(({ chainId }) => chainId),
  nonce,
  issuedAt: new Date().toISOString(),
});
const signature = await signer.signMessage(siweMessage);

const response = await fetch(`https://auth.evedex.com/auth/user/sign-up`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    wallet: address,
    message: siweMessage,
    nonce,
    signature,
  }),
});
if (response.status >= 400) {
  throw new Error('Invalid auth');
}

const { token } = await response.json();
```

--------------------------------

### GET https://docs.evedex.com/glossary.md?ask=<question>&goal=<end_goal>

Source: https://docs.evedex.com/llms.txt

Performs a documentation query using the 'ask' parameter to get a direct answer with relevant excerpts. The 'goal' parameter is optional and helps tailor the answer to the user's broader objective.

```APIDOC
## GET https://docs.evedex.com/glossary.md?ask=<question>&goal=<end_goal>

### Description
Performs a documentation query using the 'ask' parameter to get a direct answer with relevant excerpts and sources. The 'goal' parameter is optional and helps tailor the answer to the user's broader objective.

### Method
GET

### Endpoint
https://docs.evedex.com/glossary.md?ask=<question>&goal=<end_goal>

### Parameters
#### Query Parameters
- **ask** (string) - Required - The immediate question, specific and self-contained, written in natural language.
- **goal** (string) - Optional - The broader end goal the user is trying to accomplish, used to tailor the answer.

### Response
#### Success Response (200)
- **answer** (string) - Direct answer to the question.
- **excerpts** (array) - Relevant excerpts from the documentation.
- **sources** (array) - Sources of the excerpts.

#### Response Example
{
  "answer": "...",
  "excerpts": ["..."],
  "sources": ["..."]
}
```

--------------------------------

### Full Evedex SDK Usage Example

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

A complete implementation demonstrating how to initialize the SDK, subscribe to market data, fetch account information, and manage orders using both wallet and API key accounts.

```typescript
import * as evedexSdk from "@evedex/exchange-bot-sdk";
import { AxiosError } from "axios";
import WebSocket from "ws";

const cfg = {
  centrifugeWebSocket: WebSocket,
  // your wallet private key
  wallets: { myWallet: { privateKey: "5b7..." } },
  // your api key
  apiKeys: { myApiKey: { apiKey: "GNL+Y/VgRj..." } },
};

const container = new evedexSdk.DemoContainer(cfg); // or ProdContainer
const gateway = container.gateway(); // for public api methods

const sampleMarketData = async () => {
  //let's subscribe to the order book update and print 1st value
  console.log("Subscribing to order book update");
  gateway.onOrderBookUpdate((o) => {
    console.log(o);
    gateway.unListenOrderBook("BTCUSDT:DEMO");
  });
  gateway.listenOrderBook("BTCUSDT:DEMO");

  //let's subscribe to the order book best update and print 1st value
  console.log("Subscribing to order book best update");
  gateway.onOrderBookBestUpdate((o) => {
    console.log(o);
    gateway.unListenOrderBookBest("BTCUSDT:DEMO");
  });
  gateway.listenOrderBookBest("BTCUSDT:DEMO");

  //let's fetch orderbook directly
  console.log(await gateway.fetchMarketDepth({ instrument: "BTCUSDT:DEMO", maxLevel: 10 }));

  //let's fetch instruments
  console.log(
    (await container.gateway().fetchInstrumentsWithMetrics()).find(
      (i) => i.name === "BTCUSDT:DEMO",
    ),
  );
  console.log(
    (await container.gateway().fetchInstruments()).find((i) => i.name === "BTCUSDT:DEMO"),
  );

  //lets fetch coins
  console.log((await gateway.fetchCoins()).find((c: any) => c.name === "BTC"));
  console.log(await gateway.fetchTrades({ instrument: "BTCUSDT:DEMO" }));
};

const sampleAccountData = async (account: evedexSdk.WalletAccount | evedexSdk.ApiKeyAccount) => {
  //show account info
  console.log(await account.fetchMe());
  const accountState = account.getBalance(); // for account ws callbacks and state
  // let's subscribe to account state metrics
  await accountState.listen(); //await is important here as it will wait till cache is populated
  console.log("Account metrics subscription done, getting state now:");

  // log current state from cache
  console.log(accountState.getOrderList().filter((o) => o.status === evedexSdk.OrderStatus.New));
  console.log(accountState.getFundingQuantity(evedexSdk.CollateralCurrency.USDT));
  console.log(accountState.getAvailableBalance());
  console.log(accountState.getPositionList());
  console.log(accountState.getTpSlList());
  console.log(accountState.getPower("BTCUSDT:DEMO"));

  //also we can fetch the same data from gateway directly
  console.log(await account.fetchOrders({ instrument: "BTCUSDT:DEMO" }));
  console.log(await account.fetchPositions());
  console.log(await account.fetchAvailableBalance());
  console.log(await account.fetchTpSlList({ instrument: "BTCUSDT:DEMO" }));

  //now let's attach callbacks to account updates to print new values
  console.log("Subscribing to account updates");
  accountState.onAccountUpdate((a) => console.info(a));
  accountState.onFundingUpdate((f) => console.info(f));
  accountState.onPositionUpdate((p) => console.info(p));
  accountState.onOrderUpdate((o) => console.info(o));
  accountState.onTpSlUpdate((t) => console.info(t));
};

const sampleOrders = async (account: evedexSdk.WalletAccount) => {
  // //this is how leverage is managed
  await account.updatePosition({ instrument: "BTCUSDT:DEMO", leverage: 20 });

  console.log("Placing limit order");
  const md = await gateway.fetchMarketDepth({ instrument: "BTCUSDT:DEMO", maxLevel: 1 });

  const limitOrder = {
    instrument: "BTCUSDT:DEMO",
    side: evedexSdk.Side.Buy,
    quantity: 0.001,
    limitPrice: md.bids[0].price - 500,
    leverage: 20,
  };
  const order = await account.createLimitOrder(limitOrder);
  console.info(`Order created: ${order.id}`);
  console.log("Cancelling limit order...");

  await account.cancelOrder({ orderId: order.id });
  try {
    //both queries will fail with 400 as order is already cancelled
    await account.massCancelUserOrders({ instrument: "BTCUSDT:DEMO" });
    await account.massCancelUserOrdersById({ orderIds: [order.id] });
  } catch (e: any) {
    if (e instanceof AxiosError) console.log(e.response?.data.error);
  }
};

const main = async () => {
  const account = await container.account("myWallet"); // for account methods
  const apiKeyAccount = await container.apiKeyAccount("myApiKey"); // for readonly account methods via api key
  console.log("Init done");

  await sampleMarketData();
  await sampleAccountData(apiKeyAccount); // or apiKeyAccount
  await sampleOrders(account); //order placements only for wallet account

  console.log("Done");
};

main().catch((e) => console.error(e));
```

--------------------------------

### createLimitOrder method usage

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Example of creating a signed limit order with take-profit and stop-loss settings.

```typescript
import { WebSocket } from "ws";
import {
  Environment,
  Container,
  type LimitOrderPayload,
  Side,
  TpSlType,
} from "@evedex/exchange-bot-sdk";

const config = {
  environment: Environment.DEV,
  centrifugeWebSocket: WebSocket,
  wallets: {
    myWallet: {
      privateKey: "your-private-key",
    },
  },
  apiKeys: {
    mainApiKey: {
      apiKey: "your-api-key",
    },
  },
};

const devContainer = new Container(config);
const walletAccount = devContainer.account("myWallet");
const limitOrderPayload: LimitOrderPayload = {
  instrument: "BTCUSDT",
  side: Side.Buy,
  leverage: 10,
  quantity: 0.01,
  limitPrice: 100000,
  tpsl: [
    {
      type: TpSlType.TakeProfit,
      side: Side.Buy,
      quantity: 0.01,
      price: 120000,
    },
    {
      type: TpSlType.StopLoss,
      side: Side.Buy,
      quantity: 0.01,
      price: 80000,
    },
  ],
};
const createLimitOrderResult = await walletAccount.createLimitOrder(limitOrderPayload);
```

```json
{
  "id": "a6f1c4e5-3b7d-42e6-b6b3-a4c65a6d43e6",
  "user": "67890",
  "instrument": "BTCUSDT",
  "side": "BUY",
  "type": "LIMIT",
  "quantity": 0.01,
  "cashQuantity": 0,
  "limitPrice": 100000,
  "stopPrice": null,
  "status": "NEW",
  "unFilledQuantity": 0.01,
  "filledAvgPrice": 0,
  "realizedPnL": 0,
  "fee": [
    {
      "coin": "USDT",
      "quantity": 10.0
    }
  ],
  "createdAt": "2022-01-01T12:00:00.000Z",
  "updatedAt": "2022-01-15T14:30:00.000Z",
  "triggeredAt": null,
  "group": "manually"
}
```

--------------------------------

### Balance sample: listen and fetch account data

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Initialize a wallet account, get the Balance instance, listen for exchange events, and fetch cached and REST data like power and orders.

```typescript
import * as evedexSdk from "@evedex/exchange-bot-sdk";

const container = new evedexSdk.DemoContainer({
  centrifugeWebSocket: WebSocket,
  wallets: {
    baseAccount: {
      privateKey: "0x...",
    },
  },
});

const account = await container.account("baseAccount");

const balance = account.getBalance();

balance.listen();

console.log(balance.getPower("BTCUSDT:DEMO"));

console.log(await balance.fetchOrders({ instrument: "BTCUSDT:DEMO" }));

balance.onAccountUpdate((a) => console.info(a));
```

--------------------------------

### Query documentation with ask and goal parameters

Source: https://docs.evedex.com/developers

Query the documentation dynamically by performing an HTTP GET request on the current page URL with the `ask` query parameter and the optional `goal` query parameter. The response contains a direct answer and relevant excerpts and sources.

```http
GET https://docs.evedex.com/developers.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### Balance JSON Structure

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Example of the JSON structure returned for an account balance.

```json
{
  "id": "1-BTCUSDT",
  "user": "johnDoe",
  "instrument": "BTCUSDT",
  "side": "BUY",
  "quantity": 0.1,
  "avgPrice": 50000,
  "fundingRate": 0.01,
  "leverage": 5,
  "maintenanceMargin": 100,
  "createdAt": "2022-01-01T12:00:00.000Z",
  "updatedAt": "2022-01-01T12:00:00.000Z"
}
```

--------------------------------

### Query documentation with ask parameter

Source: https://docs.evedex.com/8CpKd64Ce4twoEnLO6cg/legal/terms-of-use

Use this HTTP GET request to ask a question about the documentation. The `ask` parameter is required and should be a specific, self-contained question; `goal` is optional and describes the broader end goal. The response contains a direct answer with relevant excerpts and sources.

```http
GET https://docs.evedex.com/legal/global/terms-of-use-global.md?ask=<question>&goal=<end_goal>
```

--------------------------------

### GoLang EIP-712 signature generation example

Source: https://docs.evedex.com/developers/developers/toolkit.md

Example of generating an EIP-712 typed data signature using GoLang libraries (go-ethereum). It defines a domain and typed data structure, hashes the struct, and signs the final hash with a private key. Use this as a reference for implementing order signing in Go.

```go
import (
    "github.com/ethereum/go-ethereum/signer/core/apitypes"
    "github.com/ethereum/go-ethereum/crypto"
    "math/big"
)

domain := apitypes.TypedDataDomain{
    Name:              "MyDapp",
    Version:           "1",
    ChainId:           big.NewInt(1),
    VerifyingContract: "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC",
}

typedData := apitypes.TypedData{
    Types: apitypes.Types{
        "Mail": {
            {Name: "from", Type: "Person"},
            {Name: "to", Type: "Person"},
            {Name: "contents", Type: "string"},
        },
        "Person": {
            {Name: "name", Type: "string"},
            {Name: "wallet", Type: "address"},
        },
    },
    PrimaryType: "Mail",
    Domain:      domain,
    Message: map[string]interface{}{
        "from": map[string]interface{}{
            "name":   "Alice",
            "wallet": "0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826",
        },
        "to": map[string]interface{}{
            "name":   "Bob",
            "wallet": "0xaBbACaBaa0000000000000000000000000000000",
        },
        "contents": "Hello, Bob!",
    },
}

hash, err := typedData.HashStruct(typedData.PrimaryType, typedData.Message)
domainSeparator, _ := typedData.HashDomain()

finalHash := crypto.Keccak256(
    []byte("\x19\x01"),
    domainSeparator,
    hash,
)

privateKey, _ := crypto.HexToECDSA("your_private_key")
signature, _ := crypto.Sign(finalHash, privateKey)
```

--------------------------------

### Balance JSON structure

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Example of the balance data structure containing buy and sell values.

```json
{
  "buy": 1000,
  "sell": 1500
}
```

--------------------------------

### replaceLimitOrder method usage

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Example of updating an existing open limit order using the replaceLimitOrder method.

```typescript
import { WebSocket } from "ws";
import {
  Environment,
  Container,
  type ReplaceLimitOrder,
  Side,
  TpSlType,
} from "@evedex/exchange-bot-sdk";

const config = {
  environment: Environment.DEV,
  centrifugeWebSocket: WebSocket,
  wallets: {
    myWallet: {
      privateKey: "your-private-key",
    },
  },
  apiKeys: {
    mainApiKey: {
      apiKey: "your-api-key",
    },
  },
};

const devContainer = new Container(config);
const walletAccount = devContainer.account("myWallet");
const replaceLimitOrderPayload: ReplaceLimitOrder = {
  orderId: "a8f5e2b4-4c9a-4e3a-8f6d-5b4c7a9d2e1f",
  quantity: 0.02,
  limitPrice: 105000,
};
const replaceLimitOrderResult = await walletAccount.replaceLimitOrder(replaceLimitOrderPayload);
```

```json
{
  "id": "a8f5e2b4-4c9a-4e3a-8f6d-5b4c7a9d2e1f",
  "user": "67890",
  "instrument": "BTCUSDT",
  "side": "BUY",
  "type": "LIMIT",
  "quantity": 0.02,
  "cashQuantity": 0,
  "limitPrice": 105000,
  "stopPrice": null,
  "status": "REPLACED",
  "unFilledQuantity": 0.02,
  "filledAvgPrice": 0,
  "realizedPnL": 0,
  "fee": [
    {
      "coin": "USDT",
      "quantity": 10.0
    }
  ],
  "createdAt": "2022-01-01T12:00:00.000Z",
  "updatedAt": "2022-01-15T14:30:00.000Z",
  "triggeredAt": null,
  "group": "manually"
}
```

--------------------------------

### GET /api/market/available-balance API response sample (JSON)

Source: https://docs.evedex.com/developers/developers/personalized_user_data.md

Sample JSON response from the available-balance endpoint. Shows funding balance, open positions, open orders, and the computed availableBalance. Available balance is affected by open orders and current trading results.

```JSON
{
  "currency": "usdt",
  "funding": {
    "currency": "usdt",
    "balance": 108.25334509
  },
  "position": [
    {
      "instrument": "ETHUSD",
      "side": "BUY",
      "volume": "73.5832",
      "initialMargin": "3.67916"
    }
  ],
  "negativeUnPnL": 0,
  "openOrder": [
    {
      "instrument": "BTCUSD",
      "side": "BUY",
      "unFilledVolume": "587.5",
      "unFilledInitialMargin": "5.875"
    }
  ],
  "positions": {
    "BTCUSD:BUY": 0,
    "ETHUSD:SELL": 0
  },
  "openOrders": {
    "BTCUSD:BUY": 587.5
  },
  "availableBalance": 102.37834509,
  "updatedAt": "2025-07-24T16:31:32.582Z"
}
```

--------------------------------

### Example WebSocket payload for last candlestick

Source: https://docs.evedex.com/developers/developers/market_data.md

Example payload from the WebSocket feed, identical to the REST candle representation: timestamp, open, close, high, low, volumeUsd, and volume.

```text
[1763494975613, 93545.491, 93436.58650459, 93545.491, 93325.95, 2242.47807611016, 0.024]
```

--------------------------------

### Container.constructor(config: ContainerConfig)

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Initializes a new Container instance with the provided configuration, including environment, WebSocket implementation, wallets, and API keys.

```APIDOC
## Container.constructor(config: ContainerConfig)

### Description
Initializes a new Container instance with the provided configuration.

### Method
constructor

### Parameters
- **config** (ContainerConfig) - Required - Configuration object containing environment, centrifugeWebSocket, wallets, and apiKeys.

### Request Example
```typescript
import { WebSocket } from "ws";
import { Environment, Container } from "@evedex/exchange-bot-sdk";

const config = {
  environment: Environment.DEV,
  centrifugeWebSocket: WebSocket,
  wallets: {
    myWallet: {
      privateKey: "your-private-key",
    },
  },
  apiKeys: {
    mainApiKey: {
      apiKey: "your-api-key",
    },
  },
};

const devContainer = new Container(config);
```
```

--------------------------------

### Get Position List

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Retrieves all positions associated with the balance.

```typescript
import { WebSocket } from "ws";
import { Environment, Container, CollateralCurrency } from "@evedex/exchange-bot-sdk";

const config = {
  environment: Environment.DEV,
  centrifugeWebSocket: WebSocket,
  wallets: {
    myWallet: {
      privateKey: "your-private-key",
    },
  },
  apiKeys: {
    mainApiKey: {
      apiKey: "your-api-key",
    },
  },
};

const devContainer = new Container(config);

const walletAccount = await devContainer.account("myWallet");

const balance = walletAccount.getBalance();

await balance.listen();

const positions = balance.getPositionList();
```

```json
[
  {
    "id": "1-BTCUSDT",
    "user": "johnDoe",
    "instrument": "BTCUSDT",
    "side": "BUY",
    "quantity": 0.1,
    "avgPrice": 50000,
    "fundingRate": 0.01,
    "leverage": 5,
    "maintenanceMargin": 100,
    "createdAt": "2022-01-01T12:00:00.000Z",
    "updatedAt": "2022-01-01T12:00:00.000Z"
  }
]
```

--------------------------------

### Initialize Balance

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Demonstrates how to initialize the Balance class using either a wallet account or an API key account.

```typescript
import { WebSocket } from "ws";
import { Environment, Container } from "@evedex/exchange-bot-sdk";

const config = {
  environment: Environment.DEV,
  centrifugeWebSocket: WebSocket,
  wallets: {
    myWallet: {
      privateKey: "your-private-key",
    },
  },
  apiKeys: {
    mainApiKey: {
      apiKey: "your-api-key",
    },
  },
};

// using wallet account

const devContainer = new Container(config);

const walletAccount = await devContainer.account("myWallet");

const balance = walletAccount.getBalance();

// or using api key account

const apiKeyAccount = await devContainer.apiKeyAccount("mainApiKey");

const balanceFromApiKeyAccount = apiKeyAccount.getBalance();
```

--------------------------------

### Initialize Container

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Demonstrates how to initialize a Container instance using the ContainerConfig object.

```typescript
import { WebSocket } from "ws";
import { Environment, Container } from "@evedex/exchange-bot-sdk";

const config = {
  environment: Environment.DEV,
  centrifugeWebSocket: WebSocket,
  wallets: {
    myWallet: {
      privateKey: "your-private-key",
    },
  },
  apiKeys: {
    mainApiKey: {
      apiKey: "your-api-key",
    },
  },
};

const devContainer = new Container(config);
```

--------------------------------

### Initialize DemoContainer for demo trading environment

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Create a DemoContainer instance for testing purposes, passing the WebSocket class, a wallet with a private key, and an empty apiKeys object.

```typescript
const container = new evedexSdk.DemoContainer({
  centrifugeWebSocket: WebSocket,
  wallets: {
    baseAccount: {
      privateKey: "0x...",
    },
  },
  apiKeys: {},
});
```

--------------------------------

### Get Funding Quantity

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Retrieves the current funding quantity for a specific collateral currency.

```typescript
import { WebSocket } from "ws";
import { Environment, Container, CollateralCurrency } from "@evedex/exchange-bot-sdk";

const config = {
  environment: Environment.DEV,
  centrifugeWebSocket: WebSocket,
  wallets: {
    myWallet: {
      privateKey: "your-private-key",
    },
  },
  apiKeys: {
    mainApiKey: {
      apiKey: "your-api-key",
    },
  },
};

const devContainer = new Container(config);

const walletAccount = await devContainer.account("myWallet");

const balance = walletAccount.getBalance();

await balance.listen();

const funding = balance.getFundingQuantity(CollateralCurrency.USDT); // Example: returns "1000"
```

--------------------------------

### Get Position by Instrument

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Retrieves a specific user position based on the provided instrument name.

```typescript
import { WebSocket } from "ws";
import { Environment, Container } from "@evedex/exchange-bot-sdk";

const config = {
  environment: Environment.DEV,
  centrifugeWebSocket: WebSocket,
  wallets: {
    myWallet: {
      privateKey: "your-private-key",
    },
  },
  apiKeys: {
    mainApiKey: {
      apiKey: "your-api-key",
    },
  },
};

const devContainer = new Container(config);

const walletAccount = await devContainer.account("myWallet");

const balance = walletAccount.getBalance();

await balance.listen();

const position = balance.getPosition("BTCUSDT");
```

--------------------------------

### Initialize wallet account with DemoContainer

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Initialize a wallet account using the DemoContainer class, providing a wallet with a private key. This account type supports order, position, and balance methods.

```typescript
import * as evedexSdk from "@evedex/exchange-bot-sdk";

const container = new evedexSdk.DemoContainer({
  centrifugeWebSocket: WebSocket,
  wallets: {
    baseAccount: {
      privateKey: "0x...",
    },
  },
});
```

--------------------------------

### Create Take Profit/Stop Loss Order

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Demonstrates how to initialize a container and create a TP/SL order using the createTpSl method.

```typescript
import { WebSocket } from "ws";
import {
  Environment,
  Container,
  type TpSlCreatePayload,
  Side,
  TpSlType,
} from "@evedex/exchange-bot-sdk";

const config = {
  environment: Environment.DEV,
  centrifugeWebSocket: WebSocket,
  wallets: {
    myWallet: {
      privateKey: "your-private-key",
    },
  },
  apiKeys: {
    mainApiKey: {
      apiKey: "your-api-key",
    },
  },
};

const devContainer = new Container(config);
const walletAccount = devContainer.account("myWallet");
const tpslPayload: TpSlCreatePayload = {
  type: TpSlType.TakeProfit,
  side: Side.Buy,
  quantity: 0.01,
  price: 120000,
  order: "4f6c21a4-3c4f-4f2e-8f6d-5b4c7a9d2e1f",
  instrument: "BTCUSDT",
};
const createTpSlResult = await walletAccount.createTpSl(tpslPayload);
```

```json
{
  "id": "a8f5e2b4-4c9a-4e3a-8f6d-5b4c7a9d2e1f",
  "instrument": "BTCUSD",
  "type": "take-profit",
  "side": "BUY",
  "quantity": "0.01",
  "price": "120000",
  "status": "waitOrder",
  "triggerOrder": null,
  "triggeredQuantity": "0",
  "cancelledReason": "",
  "createdAt": "2023-02-20T14:30:00.000Z",
  "updatedAt": "2023-02-20T14:30:00.000Z"
}
```

--------------------------------

### Get Pending Withdraw Transfers

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Returns the sum of pending withdraw transfers for a specific collateral currency.

```typescript
import { WebSocket } from "ws";
import { Environment, Container, CollateralCurrency } from "@evedex/exchange-bot-sdk";

const config = {
  environment: Environment.DEV,
  centrifugeWebSocket: WebSocket,
  wallets: {
    myWallet: {
      privateKey: "your-private-key",
    },
  },
  apiKeys: {
    mainApiKey: {
      apiKey: "your-api-key",
    },
  },
};

const devContainer = new Container(config);

const walletAccount = await devContainer.account("myWallet");

const balance = walletAccount.getBalance();

await balance.listen();

const withdrawPendingTrasferAmount = balance.getWithdrawTransferPendingQuantity(
  CollateralCurrency.USDT,
); // Example: returns Big instance
```

--------------------------------

### Initialize ProdContainer for production environment

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Create a ProdContainer instance for production use, with the same configuration structure as the demo container.

```typescript
const container = new evedexSdk.ProdContainer({
  centrifugeWebSocket: WebSocket,
  wallets: {
    baseAccount: {
      privateKey: "0x...",
    },
  },
  apiKeys: {},
});
```

--------------------------------

### WalletAccount updatePosition usage

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Example of using the updatePosition method to modify a position's leverage for a specific instrument.

```typescript
import { WebSocket } from "ws";
import { Environment, Container, type PositionUpdateQuery } from "@evedex/exchange-bot-sdk";

const config = {
  environment: Environment.DEV,
  centrifugeWebSocket: WebSocket,
  wallets: {
    myWallet: {
      privateKey: "your-private-key",
    },
  },
  apiKeys: {
    mainApiKey: {
      apiKey: "your-api-key",
    },
  },
};

const devContainer = new Container(config);
const walletAccount = devContainer.account("myWallet");
const positionUpdatePayload: PositionUpdateQuery = {
  instrument: "BTCUSDT",
  leverage: 20,
};

const updatePositionResult = await walletAccount.updatePosition(positionCloseOrderPayload);
```

```json
{
  "id": "a8f5e2b4-4c9a-4e3a-8f6d-5b4c7a9d2e1f",
  "user": "a8f5e2b4-4c9a-4e3a-8f6d-5b4c7a9d2e1n",
  "instrument": "BTCUSDT",
  "side": "BUY",
  "quantity": 10,
  "avgPrice": 100.0,
  "fundingRate": 0.01,
  "leverage": 20,
  "maintenanceMargin": 1000.0,
  "createdAt": "2023-02-20T14:30:00.000Z",
  "updatedAt": "2023-02-20T14:30:00.000Z"
}
```

--------------------------------

### Initialize API key account with initContainer and DemoContainer

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Initialize an API key account using either the initContainer function or the DemoContainer class. The apiKeys object contains a mainApiKey with an API key string.

```typescript
import * as evedexSdk from "@evedex/exchange-bot-sdk";

const container = evedexSdk.initContainer(evedexSdk.Environment.DEMO, {
  centrifugeWebSocket: WebSocket,
  wallets: {},
  apiKeys: {
    mainApiKey: {
      apiKey: "cUxD***uOUQ=",
    },
  },
});

// or
const demoContainer = new evedexSdk.DemoContainer({
  centrifugeWebSocket: WebSocket,
  wallets: {},
  apiKeys: {
    mainApiKey: {
      apiKey: "cUxD***uOUQ=",
    },
  },
});
```

--------------------------------

### GET /api/market/{instrument}/recent-trades

Source: https://docs.evedex.com/developers/developers/public_exchange_data.md

Retrieves a list of recent trades for a specific instrument, returning anonymized trade data.

```APIDOC
## GET /api/market/{instrument}/recent-trades

### Description
Retrieves a list of recent trades for a specific instrument, returning anonymized trade data.

### Method
GET

### Endpoint
/api/market/{instrument}/recent-trades

### Parameters
#### Path Parameters
- **instrument** (string) - Required - The instrument identifier.

### Response
#### Success Response (200)
- **instrument** (string) - The instrument identifier.
- **side** (string) - The trade side (buy or sell).
- **fillQuantity** (number) - The quantity filled.
- **fillPrice** (number) - The price at which the trade was filled.
- **createdAt** (string) - The timestamp of the trade.

#### Response Example
{
  "instrument": "BTC/USD",
  "side": "buy",
  "fillQuantity": 0.5,
  "fillPrice": 50000,
  "createdAt": "2023-01-01T00:00:00Z"
}
```

--------------------------------

### fetchTpSlList method usage

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Shows how to fetch a list of Take Profit and Stop Loss orders by providing specific query parameters.

```typescript
import { WebSocket } from "ws";
import { Environment, Container, TpSlType } from "@evedex/exchange-bot-sdk";

const config = {
  environment: Environment.DEV,
  centrifugeWebSocket: WebSocket,
  wallets: {
    myWallet: {
      privateKey: "your-private-key",
    },
  },
  apiKeys: {
    mainApiKey: {
      apiKey: "your-api-key",
    },
  },
};

const devContainer = new Container(config);
const apiKeyAccount = devContainer.apiKeyAccount("mainApiKey");
const query = {
  instrument: ["BTCUSDT", "ETHUSDT"],
  status: ["active", "pending"],
  type: TpSlType.TakeProfit,
  offset: 0,
  limit: 10,
};
const tpslList = await apiKeyAccount.fetchTpSlList(query);
```

```json
{
  "list": [
    {
      "id": "f47ac10b-58cc-4752-9f6a-8e3f9e7a6c11",
      "instrument": "BTCUSDT",
      "type": "take-profit",
      "side": "BUY",
      "quantity": "0.1",
      "price": "50000.00",
      "status": "active",
      "triggerOrder": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b9d4c22",
      "triggeredQuantity": "0.05",
      "cancelledReason": "",
      "createdAt": "2022-01-01T12:00:00.000Z",
      "updatedAt": "2022-01-15T14:30:00.000Z"
    }
  ]
}
```

--------------------------------

### GET /api/history/{instrument}/list

Source: https://docs.evedex.com/developers/developers/market_data.md

Retrieves historical market data (candlesticks) for a specified instrument. This endpoint is public and does not require authentication.

```APIDOC
## [GET] /api/history/{instrument}/list

### Description
Retrieves historical market data (candlesticks) for a specified instrument. This endpoint is public and does not require authentication.

### Method
GET

### Endpoint
/api/history/{instrument}/list

### Parameters
#### Path Parameters
- **instrument** (string) - Required - Instrument name, e.g. `BTCUSD`.

#### Query Parameters
- **after** (string) - Optional - Lower bound of the requested interval (inclusive), in ISO 8601 format.
- **before** (string) - Optional - Upper bound of the requested interval (inclusive), in ISO 8601 format.
- **group** (string) - Optional - Candlestick timeframe. Supported values: "1s", "1m", "3m", "5m", "15m", "30m", "1h", "4h", "6h", "12h", "1d", "1w", "1mo".

### Response
#### Success Response (200)
- **Candle** (array) - Standard Candle format: [timestamp (ms), open, close, high, low, volumeUsd, volume]

#### Response Example
```json
[
  [
    1763164800000,
    3110.975,
    3139.125,
    3149.175,
    3109.1,
    153899.39618428,
    49.14
  ],
  [
    1763168400000,
    3139.125,
    3172.545,
    3177.715,
    3122.27,
    258460.29556746,
    82
  ]
]
```

### Rate Limit
The endpoint returns up to 100,000 candlesticks in a single response.
```

--------------------------------

### getBalance()

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Creates a Balance instance to access realtime available balance and power data. Can be called from a wallet account or an API key account.

```APIDOC
## getBalance()

### Description
Creates a Balance instance to access realtime available balance and power data. Can be called from a wallet account or an API key account.

### Method
SDK Method

### Endpoint
walletAccount.getBalance() or apiKeyAccount.getBalance()

### Parameters
None

### Request Example
```typescript
const balance = walletAccount.getBalance();
// or
const balanceFromApiKeyAccount = apiKeyAccount.getBalance();
```

### Response
Returns a Balance class instance.
```

--------------------------------

### GET /api/order/opened

Source: https://docs.evedex.com/developers/developers/personalized_user_data.md

Retrieves an array of the user's open orders. Updates are also sent via Async API on the order-{userExchangeId} channel.

```APIDOC
## GET /api/order/opened

### Description
Retrieves an array of the user's open orders.

### Method
GET

### Endpoint
/api/order/opened

### Response
#### Success Response (200)
Returns an array of the user's open orders.

#### Response Example
```ts
interface Order {
  id: string;
  user: string;
  instrument: string;
  side: Side; // BUY or SELL
  type: OrderType; // LIMIT, MARKET, STOP, STOP_LIMIT
  quantity: number;
  cashQuantity: number;
  limitPrice: number;
  stopPrice: number | null;
  status: OrderStatus; // NEW, PARTIALLY_FILLED, FILLED, CANCELLED, REJECTED, EXPIRED, REPLACED
  rejectedReason?: string;
  unFilledQuantity: number;
  filledAvgPrice: number;
  realizedPnL: number;
  createdAt: string;
  updatedAt: string;
  triggeredAt: string | null;
  group: OrderGroup; // manually, tpsl, liquidation, adl
}
```

### Notes
- Compare snapshots by `updatedAt`.
- Real-time updates are sent via Async API on the `order-{userExchangeId}` channel.
```

--------------------------------

### GET /api/position

Source: https://docs.evedex.com/developers/developers/personalized_user_data.md

Retrieves an array of the user's open positions. Updates are also sent via Async API on the position-{userExchangeId} channel.

```APIDOC
## GET /api/position

### Description
Retrieves an array of the user's open positions.

### Method
GET

### Endpoint
/api/position

### Response
#### Success Response (200)
Returns an array of user positions.

#### Response Example
```ts
interface Position {
  id: string;
  user: string;
  instrument: string;
  side: Side; // BUY or SELL
  quantity: number;
  avgPrice: number;
  fundingRate: number;
  leverage: number;
  maintenanceMargin: number;
  createdAt: string;
  updatedAt: string;
}
```

### Notes
- Compare snapshots by `updatedAt` for consistency.
- Real-time updates are sent via Async API on the `position-{userExchangeId}` channel.
```

--------------------------------

### listen()

Source: https://docs.evedex.com/developers/developers/exchange_bot_sdk.md

Subscribes to exchange events and fills balance state. Returns the Balance class instance.

```APIDOC
## listen()

### Description
Subscribes to exchange events and fills balance state. Returns the Balance class instance.

### Method
SDK Method

### Endpoint
balance.listen()

### Parameters
None

### Request Example
```typescript
const balance = walletAccount.getBalance();
balance.listen();
```

### Response
Returns the Balance class instance.
```

--------------------------------

### GET api/market/{instrument}/deep

Source: https://docs.evedex.com/developers/developers/public_exchange_data.md

Retrieves the current order book depth for a specific instrument, returning grouped volume data by price levels with up to 4 decimal places.

```APIDOC
## GET api/market/{instrument}/deep

### Description
Retrieves the current order book depth for a specific instrument, returning grouped volume data by price levels with up to 4 decimal places.

### Method
GET

### Endpoint
api/market/{instrument}/deep

### Parameters
#### Path Parameters
- **instrument** (string) - Required - The instrument identifier.

### Response
#### Success Response (200)
- **t** (number) - Timestamp of the order book snapshot.
- **asks** (array) - List of ask levels, each with price and quantity.
- **bids** (array) - List of bid levels, each with price and quantity.

#### Response Example
{
  "t": 1234567890,
  "asks": [
    { "price": 100.5, "quantity": 10 }
  ],
  "bids": [
    { "price": 99.5, "quantity": 20 }
  ]
}
```

--------------------------------

### Sample JSON response for historical price data

Source: https://docs.evedex.com/developers/developers/market_data.md

Example JSON response from the historical price data endpoint, showing two candlesticks with timestamp, OHLC, volumeUsd, and volume.

```json
[
  [
    1763164800000,
    3110.975,
    3139.125,
    3149.175,
    3109.1,
    153899.39618428
    49.14,

  ],
  [
    1763168400000,
    3139.125,
    3172.545,
    3177.715,
    3122.27,
    258460.29556746
    82,
  ]
]
```

--------------------------------

### GET api/market/{instrument}/deep?marketLevel=1

Source: https://docs.evedex.com/developers/developers/public_exchange_data.md

Retrieves the best bid and ask prices for a specific instrument by using the order book depth endpoint with the marketLevel parameter set to 1.

```APIDOC
## GET api/market/{instrument}/deep?marketLevel=1

### Description
Retrieves the best bid and ask prices for a specific instrument by using the order book depth endpoint with the marketLevel parameter set to 1.

### Method
GET

### Endpoint
api/market/{instrument}/deep?marketLevel=1

### Parameters
#### Path Parameters
- **instrument** (string) - Required - The instrument identifier.

#### Query Parameters
- **marketLevel** (integer) - Required - Set to 1 to get the best bid and ask.

### Response
#### Success Response (200)
- **t** (number) - Timestamp of the order book snapshot.
- **asks** (array) - List of ask levels, each with price and quantity.
- **bids** (array) - List of bid levels, each with price and quantity.

#### Response Example
{
  "t": 1234567890,
  "asks": [
    { "price": 100.5, "quantity": 10 }
  ],
  "bids": [
    { "price": 99.5, "quantity": 20 }
  ]
}
```