> For the complete documentation index, see [llms.txt](https://docs.swapsdk.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.swapsdk.xyz/orderbook-api.md).

# 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 %}