Bids / Cancel / Accept

A Route that returns bidding offers data for any inscription listed on your platform. A Route that can initiate bidding requests for any inscription listed on your platform

Good To Know: If bidding has not been supported in your site, please skip this chapter, it's optional for the integration.

Fetch Bids

GET https://api.yourapi.com/bids

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

Query Parameters

Name	Type	Description
collection_slug	String	The identifier of the collection in your database
inscription_id	String	The identifier of the listed inscription, which is generated by Ordinals protocol. Such as e583ba055949cd05bb145249b20dd5076cb81d46e0bb84158a17305fcc77aa05i0
order_by	String	price, bided_at
bidder	String	Bidder BTC address
by_ordyssey	Bool	Some inscriptions are bided via our bidding-copy functions, so we need this field to do some tracking under our business. If true, only returns bids by us.
order_id	String	A unique identifier (UUID) for your platform to save every listing or bidding order by user

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
order_id*	String	A unique identifier 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
price*	Int	Bidding price (in sats) by bidder
bided_at*	Timestamp	UTC timestamp, 1632099515
by_ordyssey	Bool	Some inscriptions are bided via our bidding-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.
bidder*	String	Bidder BTC address

Place Bid Step 1 (Generate unsigned PSBT)

POST https://api.yourapi.com/bid/{inscription_id}/gen_unsigned_psbt

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
price*	Int	Bidding Price
payment_address*	String	Bidder BTC Wallet Address for payment
payment_public_key*	String	The public key or tapInternalKey of the bidder wallet
receive_address*	String	Bidder BTC Wallet Address for receiving 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 saved into your database
}

403: Forbidden Some inscriptions cannot be bided

Place Bid Step 2 (Send back the signed PSBT)

POST https://api.yourapi.com/bid/{inscription_id}/signed_psbt_callback

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
signed_psbt*	String	Signed PSBT by client side
order_id*	String	The UUID of the order generated by last step

200: OK Successfully placed a bid

400: Bad Request Validation error for the signed data

Cancel Bid

POST https://api.yourapi.com/cancel_bid/{inscription_id}

Path Parameters

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

Request Body

Name	Type	Description
public_key*	String	The public key of the bidder's BTC wallet
order_id*	String	The UUID of the bidding order generated by the platform

200: OK

400: Bad Request

Accept Bid Step 1 (Generate unsigned PSBT)

POST https://api.yourapi.com/accept_bid/{inscription_id}/gen_unsigned_psbt

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
public_key*	String	The public key or tapInternalKey of the bidder wallet
order_id*	String	The UUID of the bidding order

200: OK Return a unsigned PSBT

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

403: Forbidden The bid cannot be accepted

Accept Bid Step 2 (Send back the signed PSBT)

POST https://api.yourapi.com/accept_bid/{inscription_id}/signed_psbt_callback

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
signed_psbt*	String	Signed PSBT by client side of the inscription owner
order_id*	String	The UUID of the bidding order

200: OK Successfully accepted

400: Bad Request Validation error for the signed data