Buy Tokens

post

https://api.reservoir.tools/execute/buy/v7

Use this API to fill listings. We recommend using the SDK over this API as the SDK will iterate through the steps and return callbacks. Please mark excludeEOA as true to exclude Blur orders.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

🚧
We recommend using Reservoir SDK
Reservoir SDK includes helpers that abstract the process of using the Trading API such as iterating through execution steps and returning callbacks that can be used to update your UI. The SDK can reduce the chance of errors. If you are developing in TS/JS we recommend using the ReservoirSDK.

Body Params

items

array of objects

required

length ≥ 1

List of items to buy.

items*

collection

string

Collection to buy.

token

string

Token to buy.

quantity

integer

Quantity of tokens to buy.

orderId

string

Optional order id to fill.

rawOrder

object

Optional raw order to fill.

fillType

string

enum

Defaults to preferMint

Specify preferred fillType. preferMint: First, tries to mint a new NFT if available; otherwise, it purchases from the secondary market. trade: Always buys from the secondary market, regardless of price. mint: Always mints a new NFT.

Allowed:

preferredMintStage

string

Optionally specify a stage to mint

preferredOrderSource

string

If there are multiple listings with equal best price, prefer this source over others.
NOTE: if you want to fill a listing that is not the best priced, you need to pass a specific order id or use exactOrderSource.

exactOrderSource

array of strings

length ≤ 2

exactOrderSource

exclusions

array of objects

Items to exclude

exclusions

taker

string

required

Address of wallet filling (receiver of the NFT).

relayer

string

Address of wallet relaying the fill transaction (paying for the NFT).

onlyPath

boolean

Defaults to false

If true, only the path will be returned.

forceRouter

boolean

If true, all fills will be executed through the router (where possible)

forwarderChannel

string

If passed, all fills will be executed through the trusted trusted forwarder (where possible)

currency

string

Currency to be used for purchases.

currencyChainId

number

The chain id of the purchase currency

normalizeRoyalties

boolean

Defaults to false

Charge any missing royalties.

allowInactiveOrderIds

boolean

Defaults to false

If true, inactive orders will not be skipped over (only relevant when filling via a specific order id).

source

string

Filling source used for attribution. Example: reservoir.market

feesOnTop

array of strings

List of fees (formatted as feeRecipient:feeAmount) to be taken when filling.
Unless overridden via the currency param, the currency used for any fees on top matches the buy-in currency detected by the backend.
Example: 0xF296178d553C8Ec21A2fBD2c5dDa8CA9ac905A00:1000000000000000

feesOnTop

partial

boolean

Defaults to false

If true, any off-chain or on-chain errors will be skipped.

skipBalanceCheck

boolean

Defaults to false

If true, balance check will be skipped.

excludeEOA

boolean

Defaults to false

Exclude orders that can only be filled by EOAs, to support filling with smart contracts. If marked true, blur will be excluded.

maxFeePerGas

string

Optional custom gas settings. Includes base fee & priority fee in this limit.

maxPriorityFeePerGas

string

Optional custom gas settings.

usePermit

boolean

When true, will use permit to avoid approvals.

swapProvider

string

enum

Defaults to uniswap

Choose a specific swapping provider when buying in a different currency (defaults to relay)

Allowed:

executionMethod

string

enum

Allowed:

referrer

string

Referrer address (where supported)

comment

string

Mint comment (where suported)

conduitKey

string

Conduit key to use to fulfill the order

x2y2ApiKey

string

Optional X2Y2 API key used for filling.

openseaApiKey

string

Optional OpenSea API key used for filling. You don't need to pass your own key, but if you don't, you are more likely to be rate-limited.

blurAuth

string

Advanced use case to pass personal blurAuthToken; the API will generate one if left empty.

We recommend using Reservoir SDK

200Successful