Matches

Query historical matches for a given subaccount or provided products.

Rate limits

• Dynamic based on limit param provided (weight = 2 + limit / 10)

  • E.g: With limit=100, you can make up to 200 requests per min or 33 requests / 10 secs.

See more details in API Rate limits

Request

Matches by subaccount

Query subaccount matches ordered by submission index desc. Response includes order fill and fee information.

POST [ARCHIVE_ENDPOINT]

Body

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

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

Request Parameters

Parameter	Type	Required	Description
subaccount	string	No	A bytes32 sent as a hex string; includes the address and the subaccount identifier.
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

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.

{
  "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,
      "pre_balance": {
        "base": {
          "perp": {
            "product_id": 2,
            "lp_balance": {
              "amount": "0",
              "last_cumulative_funding_x18": "1823351297710837"
            },
            "balance": {
              "amount": "2686684000000000000000",
              "v_quote_balance": "-76348662407149297671587247",
              "last_cumulative_funding_x18": "134999841911604906604576"
            }
          }
        },
        "quote": null
      },
      "post_balance": {
        "base": {
          "perp": {
            "product_id": 2,
            "lp_balance": {
              "amount": "0",
              "last_cumulative_funding_x18": "1823351297710837"
            },
            "balance": {
              "amount": "2686013000000000000000",
              "v_quote_balance": "-76328351274188497671587247",
              "last_cumulative_funding_x18": "134999841911604906604576"
            }
          }
        },
        "quote": null
      }
    },
    {
      "digest": "0x0f6e5a0434e36d8e6d4fed950d3624b0d8c91a8a84efd156bb25c1382561c0c2",
      "order": {
        "sender": "0x12a0b4888021576eb10a67616dd3dd3d9ce206b664656661756c740000000000",
        "priceX18": "27540000000000000000000",
        "amount": "2000000000000000000",
        "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,
      "pre_balance": {
        "base": {
          "perp": {
            "product_id": 2,
            "lp_balance": {
              "amount": "0",
              "last_cumulative_funding_x18": "1823351297710837"
            },
            "balance": {
              "amount": "2686684000000000000000",
              "v_quote_balance": "-76348662407149297671587247",
              "last_cumulative_funding_x18": "134999841911604906604576"
            }
          }
        },
        "quote": null
      },
      "post_balance": {
        "base": {
          "perp": {
            "product_id": 2,
            "lp_balance": {
              "amount": "0",
              "last_cumulative_funding_x18": "1823351297710837"
            },
            "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,
              "nonce": 1761322608857448400
            },
            "signature": "0xe8fa7151bde348afa3b46dc52798046b7c8318f1b0a7f689710debbc094658cc1bf5a7e478ccc8278b625da0b9402c86b580d2e31e13831337dfd6153f4b37811b"
          },
          "maker": {
            "order": {
              "sender": "0xebdbbcdbd2646c5f23a1e0806027eee5f71b074664656661756c740000000000",
              "price_x18": "27544000000000000000000",
              "amount": "-736000000000000000",
              "expiration": 1679731669,
              "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",
              "expiration": 4611686020107120000,
              "nonce": 1761322602510418000
            },
            "signature": "0x826c68f1a3f76d9ffbe8041f8d45e969d31f1ab6f2ae2f6379d1493e479e56436091d6cf4c72e212dd2f1d2fa17c627c4c21bd6d281c77172b8af030488478b71c"
          },
          "maker": {
            "order": {
              "sender": "0xf8d240d9514c9a4715d66268d7af3b53d619642564656661756c740000000000",
              "price_x18": "27540000000000000000000",
              "amount": "-724000000000000000",
              "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.
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.
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: USDC) 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: USDC) 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.
amm	Whether the match was against the AMM.
taker	The taker order.
maker	The maker order.
timestamp	The unix epoch in seconds of when the transaction took place.