# Orderbook API

### Overview

Trader.xyz hosts the official orderbook for 0x v4 NFT orders.

Trader.xyz orderbook is an open orderbook that keeps track of off-NFT chain orders and order statuses in real-time. Anyone can add orders to the orderbook as long as they are valid 0x v4 orders.

Having an open orderbook for NFT orders makes it much easier for integrators to build NFT marketplaces and swapping apps -- bring your own frontend and leverage the trader infrastructure. No lock-in and the open orderbook is completely free to use! 

### Routes:

#### Get Orders

<mark style="color:blue;">`GET`</mark> `https://api.trader.xyz/orderbook/orders`

`Fetch NFT buy and sell orders that can be filled via 0x v4`

Use query params to filter for orders

#### Query Parameters

| Name         | Type   | Description                                                                                                                                 |               |           |             |           |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | --------- | ----------- | --------- |
| nftToken     | String | <p>Contract address for the NFT</p><p>(e.g. <code>0xed5...544</code> would filter for Azuki on mainnet</p>                                  |               |           |             |           |
| nftTokenId   | String | Token ID for the NFT                                                                                                                        |               |           |             |           |
| erc20Token   | String | <p>Contract address for the ERC20</p><p>(e.g. <code>0xa</code>...<code>06eb48</code> is USDC on mainnet)</p>                                |               |           |             |           |
| chainId      | String | Chain Id (<https://chainid.network/>)                                                                                                       |               |           |             |           |
| maker        | String | Maker wallet address                                                                                                                        |               |           |             |           |
| taker        | String | Taker wallet address                                                                                                                        |               |           |             |           |
| nonce        | String | Unique nonce for order                                                                                                                      |               |           |             |           |
| sellOrBuyNft | String | <p>Filter for either buys (bids) or sells (asks) of NFTs </p><p>Accepted filter values: 'sell' or 'buy'</p>                                 |               |           |             |           |
| status       | String | <p>Filter by real-time order status</p><p>Accepted values: 'open'                                                                           | 'filled'      | 'expired' | 'cancelled' | 'all'</p> |
| visibility   | String | <p>Filter by whether an order is public or private (private meaning the order has a specific taker address)</p><p>Accepted values: 'public' | 'private'</p> |           |             |           |
| offset       | String | <p>Offset fetching orders</p><p>Defaults to <code>0</code></p>                                                                              |               |           |             |           |
| limit        | String | <p>Amount of orders to fetch</p><p>Defaults to <code>200</code>. Max is <code>1000</code></p>                                               |               |           |             |           |

{% tabs %}
{% tab title="200: OK Returns an object which includes an `orders` field containing an array of orders" %}

```javascript
{
    "orders": [
      {
        "erc20Token": "0x31f42841c2db5173425b5223809cf3a38fede360",
        "erc20TokenAmount": "100000000000",
        "nftToken": "0x080ac75de7c348ae5898d6f03b894c6b2740179f",
        "nftTokenId": "1",
        "nftTokenAmount": "5",
        "nftType": "ERC1155",
        "sellOrBuyNft": "sell",
        "chainId": "3",
        "order": {
            "direction": 0,
            "erc20Token": "0x31f42841c2db5173425b5223809cf3a38fede360",
            "erc20TokenAmount": "100000000000",
            "erc1155Token": "0x080ac75de7c348ae5898d6f03b894c6b2740179f",
            "erc1155TokenId": "1",
            "erc1155TokenAmount": "5",
            "erc1155TokenProperties": [],
            "expiry": "2524604400",
            "fees": [],
            "maker": "0xabc23f70df4f45dd3df4ec6da6827cb05853ec9b",
            "nonce": "0x95cb442a6c40447397735b97a6265507",
            "signature": {
            "r": "0x40d064b246aaa46f7fc6f0b21d11329d62aa822b9ef0a848a64e68c12c25f8ee",
            "s": "0x74dac794840285584a30c88c37aaafe113642be3133651a375672b695c362861",
            "v": 27,
            "signatureType": 2
            },
            "taker": "0x0000000000000000000000000000000000000000"
        },
        "orderStatus": {
            "status": null,
            "transactionHash": null,
            "blockNumber": null
        },
        "metadata": {}
      },
      // ...more orders
    ]
}
```

{% endtab %}
{% endtabs %}

Upon finding an order you like. use the order field as the order object to fill on 0x v4.

```typescript
const nftOrders = await fetch(
  `https://api.trader.xyz/orderbook/orders?chainId=1&nftToken=0x5Af0D9827E0c53E4799BB226655A1de152A425a5&status=open`
).then(res => res.json())

// Find the first order
const nftOrder = nftOrders[0]
// Get the actual 0x v4 order that can be filled via the ExchangeProxy
const fillableZeroExOrder = nftOrder.order

// Fill order with a) Swap SDK, or b) ethers/exchange proxy directly:

// a) Fill via Swap SdK
const swapSdk = new SwapSdkV4(provider, signer);
const tx = await swapSdk.fillSignedOrder(fillableZeroExOrder);

// b) Fill via ExchangeProxy (you will need to set up the ExchangeProxy ABI via ethers)
// The function signature looks like this:
const tx = await exchangeProxy.buyERC721(
  fillableZeroExOrder,
  fillableZeroExOrder.signature,
  '0x',
);

```

### Posting orders

<mark style="color:green;">`POST`</mark> `https://api.trader.xyz/orderbook/order`

Add a signed 0x V4 NFT order to the open orderbook

#### Request Body

| Name                                      | Type   | Description                                                                                               |
| ----------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------- |
| chainId<mark style="color:red;">\*</mark> | String | <p>Chain that the order is for</p><p>(e.g. <code>1</code> for mainnet or <code>137</code> for Polygon</p> |
| order<mark style="color:red;">\*</mark>   | String | Signed, Fillable 0x v4 NFT order                                                                          |

{% tabs %}
{% tab title="200: OK Order payload" %}

```javascript
{
  "erc20Token": "0x31f42841c2db5173425b5223809cf3a38fede360",
  "erc20TokenAmount": "100000000000",
  "nftToken": "0x080ac75de7c348ae5898d6f03b894c6b2740179f",
  "nftTokenId": "1",
  "nftTokenAmount": "5",
  "nftType": "ERC1155",
  "sellOrBuyNft": "sell",
  "chainId": "3",
  "order": {
    "direction": 0,
    "erc20Token": "0x31f42841c2db5173425b5223809cf3a38fede360",
    "erc20TokenAmount": "100000000000",
    "erc1155Token": "0x080ac75de7c348ae5898d6f03b894c6b2740179f",
    "erc1155TokenId": "1",
    "erc1155TokenAmount": "5",
    "erc1155TokenProperties": [],
    "expiry": "2524604400",
    "fees": [],
    "maker": "0xabc23f70df4f45dd3df4ec6da6827cb05853ec9b",
    "nonce": "0x95cb442a6c40447397735b97a6265507",
    "signature": {
      "r": "0x40d064b246aaa46f7fc6f0b21d11329d62aa822b9ef0a848a64e68c12c25f8ee",
      "s": "0x74dac794840285584a30c88c37aaafe113642be3133651a375672b695c362861",
      "v": 27,
      "signatureType": 2
    },
    "taker": "0x0000000000000000000000000000000000000000"
  },
  "orderStatus": {
    "status": null,
    "transactionHash": null,
    "blockNumber": null
  },
  "metadata": {}
}

```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.swapsdk.xyz/orderbook-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.