> ## Documentation Index
> Fetch the complete documentation index at: https://docs.debridge.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracking Orders

> Tracking Orders and their states via REST API.

***

# Tracking Orders via API

Once an order has been successfully created on-chain, its state can be monitored using several available methods, depending on the use case. For a
full overview of order states and their transitions, refer to the [Order
States](/dln-details/integration-guidelines/order-creation/order-tracking-api/order-states) documentation.

## Key Completion States

Orders progress through multiple internal states. However, from the perspective of the end-user experience, the following states indicate successful completion:

* `Fulfilled`
* `SentUnlock`
* `ClaimedUnlock`

<Tip>
  Any of these states can be treated as successfully completed final states for application-level logic.
</Tip>

## Quick Start

* **Base URL:** `https://dln-api.debridge.finance`
* **Full endpoint reference:** [Swagger](/api-reference/orders/get-order-by-events-by-orderid)
* **Examples:** See the implementation examples in this [GitHub
  repository](https://github.com/debridge-finance/api-integrator-example/tree/master/src/scripts/orders/queries).

## Querying Orders

### By Wallet Address

The [`POST /api/Orders/filteredList`](/api-reference/orders/get-filtered-list-of-orders-ordered-by-block-timestamp-desc-max-page-size:-100)
endpoint retrieves the current state and historical data for all orders associated with a wallet address. This endpoint is also used to populate the
trade history view in [deExplorer](https://app.debridge.com/orders).

Pagination is supported via `skip` and `take` parameters.

#### Example: Fetching Completed Orders for a Wallet

```ts theme={null}
const URL = 'https://dln-api.debridge.finance/api/Orders/filteredList';

const requestBody = {
  orderStates: ['Fulfilled', 'SentUnlock', 'ClaimedUnlock'],
  externalCallStates: ['NoExtCall'],
  skip: 0,
  take: 10,
  maker: '0x441bc84aa07a71426f4d9a40bc40ac7183d124b9',
};

const data = await post(URL, requestBody);
```

#### Example: Filtering Completed Orders by Destination Chain (e.g. HyperEVM)

```ts theme={null}
const requestBody = {
  giveChainIds: [],
  takeChainIds: [100000022], // Internal HyperEVM Chain Id
  orderStates: ['Fulfilled', 'SentUnlock', 'ClaimedUnlock'],
  externalCallStates: ['NoExtCall'],
  skip: 0,
  take: 10,
  maker: '0x441bc84aa07a71426f4d9a40bc40ac7183d124b9',
};
```

### By `referralCode`

Orders created through specific integrations can also be tracked by using the `referralCode` parameter attached to each API request.

```ts theme={null}
  const requestBody = {
    giveChainIds: [],
    // All of these are considered to be fulfilled 
    // from the end-user's perspective
    orderStates: ['Fulfilled', 'SentUnlock', 'ClaimedUnlock' ],
    externalCallStates: ['NoExtCall'],
    skip: 0,
    take: 3,
    referralCode: "31805",
  };
```

### By Transaction Hash

For inspecting a specific order, use:

```
GET /api/Orders/creationTxHash/{hash}
```

**Example:**

> [https://dln-api.debridge.finance/api/Orders/creationTxHash/
> 0x3fe11542154f53dcf3134eacb30ea5ca586c9e134c223e56bbe1893862469bc5](https://dln-api.debridge.finance/api/Orders/creationTxHash/0x3fe11542154f53dcf3134eacb30ea5ca586c9e134c223e56bbe1893862469bc5)

<Warning>
  If multiple orders were created in a single transaction, this endpoint returns data only for the **first** order.
</Warning>

#### Multiple Orders Created in the Same Transaction

To retrieve all order IDs:

```
GET /api/Transaction/{hash}/orderIds
```

**Example:**

> [https://dln-api.debridge.finance/api/Transaction/
> 0x40ee524d5bb9c4ecd8e55d23c66c5465a3f137be7ae24df366c3fd06daf7de7e
> /orderIds](https://dln-api.debridge.finance/api/Transaction/0x40ee524d5bb9c4ecd8e55d23c66c5465a3f137be7ae24df366c3fd06daf7de7e/orderIds)

**Response:**

```json theme={null}
{
  "orderIds": [
    "0x9ee6c3d0aa68a7504e619b02df7c71539d0ce10e27f593bf8604b62e51955a01"
  ]
}
```

#### Example:

```ts theme={null}
export async function getOrderIdByTransactionHash(txHash: string) {
  const URL = `https://dln-api.debridge.finance/api/Transaction/${txHash}/orderIds`;

  const response = await fetch(URL);
  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`Failed to get orderIds: ${response.statusText}. ${errorText}`);
  }

  const data = await response.json();
  if (data.error) {
    throw new Error(`DeBridge API Error: ${data.error}`);
  }

  return data;
}
```

### By `orderId`

Use this endpoint:

```
GET /api/Orders/{orderId}
```

**Example:**

> [https://dln-api.debridge.finance/api/Orders/
> 0x9ee6c3d0aa68a7504e619b02df7c71539d0ce10e27f593bf8604b62e51955a01](https://dln-api.debridge.finance/api/Orders/0x9ee6c3d0aa68a7504e619b02df7c71539d0ce10e27f593bf8604b62e51955a01)

**Response:**

```json theme={null}
{
  "status": "ClaimedUnlock"
}
```

#### Example:

```ts theme={null}
export async function getOrderStatusByOrderId(orderId: string) {
  const URL = `https://dln-api.debridge.finance/api/Orders/${orderId}`;

  const response = await fetch(URL);
  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`Failed to get order status: ${response.statusText}. ${errorText}`);
  }

  const data = await response.json();
  if (data.error) {
    throw new Error(`DeBridge API Error: ${data.error}`);
  }

  return data;
}
```

### Order Fulfillment Transaction

When order fulfillment transactions are important in the integration, they can be found inside of an each `order` returned by the API by referencing
the `fulfilledDstEventMetadata.transactionHash` field.

## Affiliate Fee Settlement

If set during order creation, the affiliate fee is automatically transferred to the `affiliateFeeRecipient` once the order reaches the `ClaimedUnlock`
status on EVM-based chains, and on Solana it is [manually withdrawable](/dln-details/affiliates/withdrawing-affiliate-fees).