Listings / List / Delist

A Route that returns all seller listings of a certain collection of your platform

Fetch listings

GET https://api.yourapi.com/v1/listings/{collection_slug}

Good to know: The Body block here means response body returns from yours, not request body from us, just for easier representation.

Path Parameters

Name	Type	Description
collection_slug*	string	The identifier of the collection in your database

Query Parameters

Name	Type	Description
order_by	string	price, listed_at
by_ordyssey	bool	Some inscriptions are listed via our listing-copy functions, so we need this field to do some tracking under our business. If true, only returns listings by us.
order_id	string	A unique identifier (UUID) for your platform to save every listing or bidding order by user
inscription_id	string	The identifier of the listed inscription, which is generated by Ordinals protocol. Such as e583ba055949cd05bb145249b20dd5076cb81d46e0bb84158a17305fcc77aa05i0

Headers

Name	Type	Description
ordyssey_http*	string	We usually use this HTTP header to allow your server identify us, or we can engage in a discussion to provide a private API token. In certain cooperative scenarios, it is important for you to be aware that the HTTP request originates from our side for the purpose of tracking contributions.

Request Body

Name	Type	Description
inscription_id*	string	The identifier of the listed inscription, which is generated by Ordinals protocol. Such as e583ba055949cd05bb145249b20dd5076cb81d46e0bb84158a17305fcc77aa05i0
by_ordyssey	bool	Some inscriptions are listed via our listing-copy functions, so we need this field to do some tracking under our business. If no by_ordyssey field was passed, we consider this as false.
price*	int	Listing price (in sats) by seller
listed_at*	timestamp	UTC timestamp, 1632099515
order_id*	string	A unique identifier for your platform to save every listing or bidding order by user

200 Listings successfully returned

[
        {
            "inscription_id": "e583ba055949cd05bb145249b20dd5076cb81d46e0bb84158a17305fcc77aa05i0",
            "listed_at": 1632099515,
            "price": 7000000, // in sats
            "by_ordyssey": true
        },
        {
            "inscription_id": "e583ba055949cd05bb145249b20dd5076cb81d46e0bb84158a17305fcc77aa05i0",
            "listed_at": 1632099518,
            "price": 9000000, // in sats
            // if no "by_ordyssey" field, we consider this as false
        }
]

401 Permission denied

Bulk List / Update Price Step 1 (Generate unsigned PSBT)

Good To Know: - Proxy Listing by Ordyssey is optional for the integration. You can choose Import Only Mode for your platform listings. - The Body block here means the element body of the final array[], not the final request body, just for easier representation.

POST https://api.yourapi.com/v1/list/gen_unsigned_psbt

Good To Know: The Body block here means the element body of the final array[], not the final request body itself, just for easier representation.

Request Body

Name	Type	Description
inscription_id*	String	The identifier of the listed inscription, which is generated by Ordinals protocol. Such as e583ba055949cd05bb145249b20dd5076cb81d46e0bb84158a17305fcc77aa05i0
seller_receive_address*	String	The seller address for receiving payment BTC from buyer
public_key*	String	The pubKey or tapInternalKey of the inscription owner's BTC address
price*	String	The listing price by seller for the inscription

200: OK Return a unsigned PSBT and an order_id

{
    "unsigned_psbt": "cHNidP8BAF4BAAAAAUJ9La+ofAcuISttLELIa/MXlpzwhespMW3ncsblUULSAAAAAAD9////AQ4LFAAAAAAAIlEgTXuI2GtwF3O204wqZnFkvNx8Pyg2bvXvHcPNPN+ZB7MAAAAAAAEA/TgBAgAAAAABAhgW2s7AuZds0CxpIxl0EpVI+ICBTDDUjpgjUwVX1WKUAAAAAAD/////qbOsCyU0AmFToZTt/L/yFx3u8G45ZV7nQ2qVKThQK0QBAAAAAP////8CLgwAAAAAAAAiUSBNe4jYa3AXc7bTjCpmcWS83Hw/KDZu9e8dw80835kHs/IIAAAAAAAAIlEgTXuI2GtwF3O204wqZnFkvNx8Pyg2bvXvHcPNPN+ZB7MBQPoPo1+VXSpwZVIhHFYAW7i3MhiQx90td5g9ZDq45CjHiojlRXccFe5wdpITvSeJhLtVifqxInd+dAfkvuKFJaQBQIZWeKzeyN9VqtOvCBcb4OOWeLYhOd5VoINqnSLenKhOGas1+ES2XkX0j6GQS9Wzdf2F7uQ3q34EZcYp3ORyyJoAAAAAAQErLgwAAAAAAAAiUSBNe4jYa3AXc7bTjCpmcWS83Hw/KDZu9e8dw80835kHswEDBIMAAAABFyBmCFHvbyWKZACC2mhNG83L5ZknaX18ujmA2/wP55dXyAAA", // Base64 format of a PSBT object
    "order_id": "90f3ab84-5867-11ee-838d-e20140f66533", // The UUID of the order in your database
    "listings": [{"inscription_id": "e583ba055949cd05bb145249b20dd5076cb81d46e0bb84158a17305fcc77aa05i0", "price": 100000},
                {"inscription_id": "e583ba055949cd05bb145249b20dd5076cb81d46e0bb84158a17305fcc77aa05i0", "price": 100000},]
}

403: Forbidden Some inscriptions cannot be listed

Bulk List / Update Price Step 2 (Send back the signed PSBT)

POST https://api.yourapi.com/v1/list/signed_psbt_callback

Request Body

Name	Type	Description
signed_psbt*	String	Signed PSBT by client side
order_id*	String	The UUID generated before for the order

200: OK Listed/updated successfully

400: Bad Request Validation error for the signed data

Delist

POST https://api.yourapi.com/v1/delist/{inscription_id}

Path Parameters

Name	Type	Description
inscription_id	String	The identifier of the listed inscription, which is generated by Ordinals protocol. Such as e583ba055949cd05bb145249b20dd5076cb81d46e0bb84158a17305fcc77aa05i0

Request Body

Name	Type	Description
seller_public_key	String	The public key or TapInternalKey of the seller's BTC wallet

200: OK

401: Unauthorized