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

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

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.

Response

Note:

  • the response includes a txs field which contains the relevant transactions for the returned matches. There are >=1 matches 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",
      "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",
      "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.

Last updated