Subscribe to sale events for any new sales, updated sales, or keep a copy of Reservoir's aggregated orderbook in sync.

How to Subscribe

View instructions here.

Subscription Options

	Value	Description
Event	sale.created	When a new sale is created
	sale.updated	When an existing sale updates data (e.g. updates to the royalties after the sale has been recorded in the database.)
	sale.deleted	When a sale is deleted (e.g. a block being reverted)
	sale.*	All ask events (created and updated)
Filters	contract	Filter to one or more contracts (e.g. 0x8d04a8c79ceb0889bdd12acdf3fa9d207ed3ff63)
	maker	Filter to one or more makers (e.g. 0xF296178d553C8Ec21A2fBD2c5dDa8CA9ac905A00)
	taker	Filter to one or more takers (e.g. 0xF296178d553C8Ec21A2fBD2c5dDa8CA9ac905A00)
	fillSource	Filter to one or more fillSource domains (e.g. opensea.io)
	orderSource	Filter to one or more orderSource domains (e.g. opensea.io)
Changed	washingTradingScore
	fees.royaltyFeeBps
	fees.marketplaceFeeBps
	fees.royaltyFeeBreakdown
	fees.marketplaceFeeBreakdown
	fees.paidFullRoyalty

The data:id will be unique for every txn; this is the same as saleId in the API.

Update Types

Any time any field in the response is updated, a sale.updated event will be emitted. Typically, what will be updated on a sale is the royalty amount if that was not included in the sale.created event.

Example `sale.created` Payload

{
    "event": "sale.created",
    "tags": {
        "contract": "0x06012c8cf97bead5deae237070f9587f8e7a266d",
        "maker": "0x89cc68f31ae2f49f3ef9be22c881efaec6ac1dcc",
        "taker": "0x7266672ea797ce9b0796e8bf26a564adec6729c3"
    },
    "changed": [],
    "data": {
        "id": "7505b231fafe9d133e156fffe82c63fe5d7a6de25075fadfc9936494e34e48d0",
        "token": {
            "contract": "0x06012c8cf97bead5deae237070f9587f8e7a266d",
            "tokenId": "2019258",
            "name": "Striker",
            "image": "https://i.seadn.io/gae/cBN53ebmNNn0I293FDryFB5pFsR2c4YcSoFymtDxpxmr4x5qMUWoiLNE-Nkgph769dv8nHfQPu9gNNeWvMgp4bSgd3qnQ5HDI1_FK1c?w=500&auto=format",
            "collection": {
                "id": "0x06012c8cf97bead5deae237070f9587f8e7a266d",
                "name": "CryptoKitties"
            }
        },
        "orderId": "0x97a0c4064bb3210e39ca8228237e485bac75e86496f4b3b4ec7d1d8583877726",
        "orderSource": "opensea.io",
        "orderSide": "ask",
        "orderKind": "seaport-v1.5",
        "from": "0x89cc68f31ae2f49f3ef9be22c881efaec6ac1dcc",
        "to": "0x7266672ea797ce9b0796e8bf26a564adec6729c3",
        "amount": "1",
        "fillSource": "opensea.io",
        "block": 17815461,
        "txHash": "0x544bb5a0ae59048f562e4fb2e5d74ee8c1e19d256b3ea1a55900a7d2b57e8507",
        "logIndex": 376,
        "batchIndex": 1,
        "timestamp": 1690836275,
        "price": {
            "currency": {
                "contract": "0x0000000000000000000000000000000000000000",
                "name": "Ether",
                "symbol": "ETH",
                "decimals": 18
            },
            "amount": {
                "raw": "35000000000000000",
                "decimal": 0.035,
                "usd": 65.16545,
                "native": 0.035
            }
        },
        "washTradingScore": 0,
        "createdAt": "2023-07-31T20:44:41.045Z",
        "updatedAt": "2023-07-31T20:44:41.045Z"
    },
    "offset": "26011238",
    "published_at": 1690836281667,
    "type": "event",
    "status": "success"
}

Example `sale.updated` Payload

{
    "event": "sale.updated",
    "tags": {
        "contract": "0x524c08be48e0b414c452da3d142c075444a2bd9e",
        "maker": "0x09846c9ed5d569b3c2429b03997ca9f7bc76393a",
        "taker": "0xef0b56692f78a44cf4034b07f80204757c31bcc9"
    },
    "changed": [
        "fees.royaltyFeeBps",
        "fees.marketplaceFeeBps",
        "fees.royaltyFeeBreakdown",
        "fees.marketplaceFeeBreakdown",
        "fees.paidFullRoyalty"
    ],
    "data": {
        "id": "04f175411b1c129f2ceaddc72893bdfbcc4e98119b72e110e00e57205fec01e3",
        "token": {
            "contract": "0x524c08be48e0b414c452da3d142c075444a2bd9e",
            "tokenId": "2353",
            "name": "krew #2353",
            "image": "https://i.seadn.io/gcs/files/d86a4d34420e9f99c9d4ef85186ddaf3.png?w=500&auto=format",
            "collection": {
                "id": "0x524c08be48e0b414c452da3d142c075444a2bd9e",
                "name": "Hippie Life Krew: The Cloudalia Story"
            }
        },
        "orderId": "0xee6c4c9863258635644c55635d6a49d560872a20627883f15ea14a6bee2b07af",
        "orderSource": "opensea.io",
        "orderSide": "ask",
        "orderKind": "seaport-v1.5",
        "from": "0x09846c9ed5d569b3c2429b03997ca9f7bc76393a",
        "to": "0xef0b56692f78a44cf4034b07f80204757c31bcc9",
        "amount": "1",
        "fillSource": "opensea.io",
        "block": 17815468,
        "txHash": "0x09d4fdf6db7cb63afcae67ea6382730c57b8a5a68fe39335e30e63f0d03d5bb5",
        "logIndex": 159,
        "batchIndex": 1,
        "timestamp": 1690836359,
        "price": {
            "currency": {
                "contract": "0x0000000000000000000000000000000000000000",
                "name": "Ether",
                "symbol": "ETH",
                "decimals": 18
            },
            "amount": {
                "raw": "55500000000000000",
                "decimal": 0.0555,
                "usd": 103.33378,
                "native": 0.0555
            },
            "netAmount": {
                "raw": "51337500000000000",
                "decimal": 0.05134,
                "usd": 95.58375,
                "native": 0.05134
            }
        },
        "washTradingScore": 0,
        "royaltyFeeBps": 500,
        "marketplaceFeeBps": 250,
        "paidFullRoyalty": true,
        "feeBreakdown": [
            {
                "kind": "royalty",
                "bps": 500,
                "recipient": "0xd1d26e8f7c71781fca279fb8d0a374fba9431193",
                "rawAmount": "2775000000000000"
            },
            {
                "kind": "marketplace",
                "bps": 250,
                "recipient": "0x0000a26b00c1f0df003000390027140000faa719",
                "rawAmount": "1387500000000000",
                "source": "opensea.io"
            }
        ],
        "createdAt": "2023-07-31T20:46:03.383Z",
        "updatedAt": "2023-07-31T20:46:06.796Z"
    },
    "offset": "26011262",
    "published_at": 1690836367266,
    "type": "event",
    "status": "success"
}

Example `sale.deleted` Payload

{
    "event": "sale.deleted",
    "tags": {
        "contract": "0x1c67d8f07d7ef2d637e61ed3fbc3fa9aaf7a6267",
        "maker": "0xf01d40c0854010862cf40c256f60d0082b611c09",
        "taker": "0xf448ba3ab40df0d3c324051ec889bbdf8aebd79f",
        "fillSource": "blur.io",
        "orderSource": "blur.io"
    },
    "changed": [],
    "data": {
        "id": "c684dc3d053ed4727d152ef7968f08813ce0a98d574ab140bd0311ea566f13ba",
        "token": {
            "contract": "0x1c67d8f07d7ef2d637e61ed3fbc3fa9aaf7a6267",
            "tokenId": "4080",
            "name": "Fractional Uprising Studios Membership #4080",
            "image": "https://i.seadn.io/s/raw/files/44cb1627d95286d75c3c5787adf66e91.png?w=500&auto=format",
            "collection": {
                "id": "0x1c67d8f07d7ef2d637e61ed3fbc3fa9aaf7a6267",
                "name": "FRACTIONAL UPRISING STUDIOS MEMBERSHIP"
            }
        },
        "orderId": "0x210010822f02c96bc42ee122521ca024ad221803f5251ded370dc8ff139e330b",
        "orderSource": "blur.io",
        "orderSide": "ask",
        "orderKind": "blur-v2",
        "from": "0xf01d40c0854010862cf40c256f60d0082b611c09",
        "to": "0xf448ba3ab40df0d3c324051ec889bbdf8aebd79f",
        "amount": "1",
        "fillSource": "blur.io",
        "block": 18587543,
        "txHash": "0xc0975819c6a4448a36ba1894d67c175966c7942eba7f32dfd21d11fb8c9c8136",
        "logIndex": 184,
        "batchIndex": 1,
        "timestamp": 1700175107,
        "price": {
            "currency": {
                "contract": "0x0000000000000000000000000000000000000000",
                "name": "Ether",
                "symbol": "ETH",
                "decimals": 18
            },
            "amount": {
                "raw": "86700000000000000",
                "decimal": 0.0867,
                "usd": 178.7438,
                "native": 0.0867
            },
            "netAmount": {
                "raw": "86275170000000000",
                "decimal": 0.08628,
                "usd": 177.86796,
                "native": 0.08628
            }
        },
        "washTradingScore": 0,
        "marketplaceFeeBps": 49,
        "paidFullRoyalty": false,
        "feeBreakdown": [
            {
                "kind": "marketplace",
                "bps": 49,
                "recipient": "0x0000a26b00c1f0df003000390027140000faa719",
                "rawAmount": "424830000000000",
                "source": "nftearth.exchange"
            }
        ],
        "createdAt": "2023-11-16T22:51:58.319Z",
        "updatedAt": "2023-11-16T22:52:02.225Z"
    },
    "offset": "33794086",
    "published_at": 1700175122368,
    "type": "event",
    "status": "success"
}

Backfilling

If you need to backfill historical data, or catch up events missed due to disconnection, you can leverage the Sales API.