Matches

Rate limits

IP weight = 2 + (limit * subaccounts.length / 10) where limit defaults to 100 (max 500) and subaccounts.length defaults to 1
- E.g: With limit=100 and 1 subaccount, weight = 12, allowing up to 200 requests per min or 33 requests / 10 secs.

{% hint style="info" %} See more details in API Rate limits {% endhint %}

Request

{% tabs %} {% tab title="Matches by subaccount" %} Query subaccounts matches ordered by submission index desc. Response includes order fill and fee information.

POST [ARCHIVE_ENDPOINT]

Body

{
  "matches": {
    "product_ids": [
      1,
      2
    ],
    "subaccounts": [
      "0x12a0b4888021576eb10a67616dd3dd3d9ce206b664656661756c740000000000"
    ],
    "max_time": 1679728762,
    "limit": 5,
    "isolated": false
  }
}

{% endtab %}

{% tab title="Matches by product" %} Query matches for provided products ordered by submission index desc. Response includes order fill and fee information.

POST [ARCHIVE_ENDPOINT]

Body

{
  "matches": {
    "product_ids": [
      1,
      2
    ],
    "max_time": "1679728762",
    "limit": 5
  }
}

{% endtab %} {% endtabs %}

Request Parameters

Parameter	Type	Required	Description
subaccounts	string[]	No	Array of `bytes32` sent as hex strings; each includes the address and the subaccount identifier. When provided, only return matches for the specified subaccounts.
product_ids	number[]	No	When provided, only return matches for the specified product ids; return matches for all products otherwise.
idx	number / string	No	When provided, only return matches with `submission_idx` <= `idx`
max_time	number / string	No	When `idx` is not provided, `max_time` (unix epoch in seconds) can be used to only return matches created <= `max_time`
limit	number	No	Max number of matches to return. defaults to `100`. max possible of `500`.
isolated	boolean	No	When provided -- - `true`: only returns matches associated to isolated positions. - `false`: only return matches associated to the cross-subaccount. defaults to `null`. In which case it returns everything. See Isolated Margin to learn more.

Response

{% hint style="info" %} Note:

the response includes a txs field which contains the relevant transactions for the returned matches. There are >=1 match events per transaction.
both matches and txs are in descending order by submission_idx.
use the submission_idx to associate a match to it's corresponding transaction.
the fee provided in the response includes taker / maker fees + sequencer fees. See fees for more details. {% endhint %}

{
  "matches": [
    {
      "digest": "0x80ce789702b670b7d33f2aa67e12c85f124395c3f9acdb422dde3b4973ccd50c",
      "order": {
        "sender": "0x12a0b4888021576eb10a67616dd3dd3d9ce206b664656661756c740000000000",
        "priceX18": "27544000000000000000000",
        "amount": "2000000000000000000",
        "expiration": "4611686020107119633",
        "nonce": "1761322608857448448"
      },
      "base_filled": "736000000000000000",
      "quote_filled": "-20276464287857571514302",
      "fee": "4055287857571514302",
      "sequencer_fee": "0",
      "cumulative_fee": "4055287857571514302",
      "cumulative_base_filled": "736000000000000000",
      "cumulative_quote_filled": "-20276464287857571514302",
      "submission_idx": "563012",
      "isolated": false,
      "is_taker": true,
      "pre_balance": {
        "base": {
          "perp": {
            "product_id": 2,
            "balance": {
              "amount": "2686684000000000000000",
              "v_quote_balance": "-76348662407149297671587247",
              "last_cumulative_funding_x18": "134999841911604906604576"
            }
          }
        },
        "quote": null
      },
      "post_balance": {
        "base": {
          "perp": {
            "product_id": 2,
            "balance": {
              "amount": "2686013000000000000000",
              "v_quote_balance": "-76328351274188497671587247",
              "last_cumulative_funding_x18": "134999841911604906604576"
            }
          }
        },
        "quote": null
      }
    },
    {
      "digest": "0x0f6e5a0434e36d8e6d4fed950d3624b0d8c91a8a84efd156bb25c1382561c0c2",
      "order": {
        "sender": "0x12a0b4888021576eb10a67616dd3dd3d9ce206b664656661756c740000000000",
        "priceX18": "27540000000000000000000",
        "amount": "2000000000000000000",
        "appendix": "1537",
        "expiration": "4611686020107119623",
        "nonce": "1761322602510417920"
      },
      "base_filled": "723999999999999999",
      "quote_filled": "-19944943483044913474043",
      "fee": "5983483044913474042",
      "sequencer_fee": "0",
      "cumulative_fee": "11958484645393618085",
      "cumulative_base_filled": "1446999999999999998",
      "cumulative_quote_filled": "-39861640484645393618087",
      "submission_idx": "563011",
      "isolated": false,
      "is_taker": true,
      "pre_balance": {
        "base": {
          "perp": {
            "product_id": 2,
            "balance": {
              "amount": "2686684000000000000000",
              "v_quote_balance": "-76348662407149297671587247",
              "last_cumulative_funding_x18": "134999841911604906604576"
            }
          }
        },
        "quote": null
      },
      "post_balance": {
        "base": {
          "perp": {
            "product_id": 2,
            "balance": {
              "amount": "2686013000000000000000",
              "v_quote_balance": "-76328351274188497671587247",
              "last_cumulative_funding_x18": "134999841911604906604576"
            }
          }
        },
        "quote": null
      }
    }
  ],
  "txs": [
    {
      "tx": {
        "match_orders": {
          "product_id": 2,
          "amm": true,
          "taker": {
            "order": {
              "sender": "0x12a0b4888021576eb10a67616dd3dd3d9ce206b664656661756c740000000000",
              "price_x18": "27544000000000000000000",
              "amount": "2000000000000000000",
              "expiration": 4611686020107120000,
              "appendix": "1537",
              "nonce": 1761322608857448400
            },
            "signature": "0xe8fa7151bde348afa3b46dc52798046b7c8318f1b0a7f689710debbc094658cc1bf5a7e478ccc8278b625da0b9402c86b580d2e31e13831337dfd6153f4b37811b"
          },
          "maker": {
            "order": {
              "sender": "0xebdbbcdbd2646c5f23a1e0806027eee5f71b074664656661756c740000000000",
              "price_x18": "27544000000000000000000",
              "amount": "-736000000000000000",
              "expiration": 1679731669,
              "appendix": "1537",
              "nonce": 1761322585591644200
            },
            "signature": "0x47f9d47f0777f3ca0b13f07b7682dbeea098c0e377b87dcb025754fe34c900e336b8c7744e021fb9c46a4f8c6a1478bafa28bf0d023ae496aa3efa4d8e81df181c"
          }
        }
      },
      "submission_idx": "563012",
      "timestamp": "1679728133"
    },
    {
      "tx": {
        "match_orders": {
          "product_id": 1,
          "amm": true,
          "taker": {
            "order": {
              "sender": "0x12a0b4888021576eb10a67616dd3dd3d9ce206b664656661756c740000000000",
              "price_x18": "27540000000000000000000",
              "amount": "2000000000000000000",
              "appendix": "1537",
              "expiration": 4611686020107120000,
              "nonce": 1761322602510418000
            },
            "signature": "0x826c68f1a3f76d9ffbe8041f8d45e969d31f1ab6f2ae2f6379d1493e479e56436091d6cf4c72e212dd2f1d2fa17c627c4c21bd6d281c77172b8af030488478b71c"
          },
          "maker": {
            "order": {
              "sender": "0xf8d240d9514c9a4715d66268d7af3b53d619642564656661756c740000000000",
              "price_x18": "27540000000000000000000",
              "amount": "-724000000000000000",
              "appendix": "1537",
              "expiration": 1679731656,
              "nonce": 1761322565506171000
            },
            "signature": "0xd8b6505b8d9b8c3cbfe793080976388035682c02a27893fb26b48a5b2bfe943f4162dea3a42e24e0dff5e2f74fbf77e33d83619140a2a581117c55e6cc236bdb1c"
          }
        }
      },
      "submission_idx": "563011",
      "timestamp": "1679728127"
    }
  ]
}

Response Fields

Matches

Field name	Description
submission_idx	Wsed to uniquely identify the blockchain transaction that generated the match; you can use it to grab the relevant transaction in the `txs` section.
isolated	Whether the match is associated with an isolated position. `true` for isolated positions, `false` for cross-subaccount positions.
is_taker	Whether the order in this match was the taker. `true` if the order was the taker, `false` if the order was the maker.
digest	The unique hash of the order.
order.sender	The sender that placed the order.
order.priceX18	The original order price.
order.amount	The original order amount.
order.expiration	The original order expiration.
order.nonce	The original order nonce.
order.appendix	The original order appendix.
pre_balance	The state of your balance before the match happened.
post_balance	The state of your balance after the match happened.
base_filled	The amount of base (e.g: BTC) filled on this match.
quote_filled	The amount of quote (e.g: USDT0) filled on this match.
fee	The amount of trading fees + sequencer fees paid on this match.
sequencer_fee	The amount of sequencer fees paid on this match.
cumulative_base_filled	The total amount of base (e.g: BTC) filled on this order up this match.
cumulative_quote_filled	The total amount of quote (e.g: USDT0) filled up to this match.
cumulative_fee	The total amount of fee paid up to this match.

Txs

Field name	Description
submission_idx	Unique identifier of the transaction.
product_id	Product associated to the transaction.
taker	The taker order.
maker	The maker order.
timestamp	The unix epoch in seconds of when the transaction took place.

14 KiB Raw Permalink Blame History

Matches

Rate limits

Request

Request Parameters

Response

Response Fields

Matches

Txs

14 KiB

Raw Permalink Blame History