OpenSea Offer Endpoints API
Offer endpoints for building, creating, fulfilling, and querying offers
Offer endpoints for building, creating, fulfilling, and querying offers
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/opensea-offer-endpoints-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: OpenSea Account Endpoints Offer Endpoints API
description: The API for OpenSea
contact:
name: OpenSea
url: https://www.opensea.io
email: contact@opensea.io
version: 2.0.0
servers:
- url: https://api.opensea.io
description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Offer Endpoints
description: Offer endpoints for building, creating, fulfilling, and querying offers
paths:
/api/v2/orders/{chain}/{protocol}/offers:
post:
tags:
- Offer Endpoints
summary: Create an item offer
description: Create an offer to purchase a single NFT (ERC721 or ERC1155).
operationId: post_offer
parameters:
- name: chain
in: path
required: true
schema:
type: string
- name: protocol
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SeaportRequest'
required: true
responses:
'200':
description: Item offer created successfully
content:
'*/*':
schema:
$ref: '#/components/schemas/Offer'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalError'
/api/v2/offers:
post:
tags:
- Offer Endpoints
summary: Create a criteria offer
description: Create a criteria offer to purchase any NFT in a collection or which matches the specified trait. For trait offers where the Build Offer endpoint returns identifierOrCriteria '0', use that value directly — trait matching is validated server-side at fulfillment time rather than via onchain merkle proof.
operationId: post_criteria_offer_v2
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OfferWithCriteriaRequest'
required: true
responses:
'200':
description: Criteria offer created successfully
content:
'*/*':
schema:
$ref: '#/components/schemas/Offer'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalError'
/api/v2/offers/fulfillment_data:
post:
tags:
- Offer Endpoints
summary: Fulfill an offer
description: Retrieve all the information, including signatures, needed to fulfill an offer directly onchain. For trait offers with identifierOrCriteria '0', the server validates that the specified token matches the offer's trait criteria before generating fulfillment data.
operationId: generate_offer_fulfillment_data_v2
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FullfillmentDataRequest'
required: true
responses:
'200':
description: Offer fulfillment data retrieved successfully
content:
'*/*':
schema:
$ref: '#/components/schemas/FulfillListingResponse'
'400':
description: 'The request is invalid
The order_hash does not exist
The chain is not an EVM Chain
The protocol_address is not a supported Seaport contract
For other error reasons, see the response data.'
content:
'*/*':
schema:
$ref: '#/components/schemas/FulfillListingResponse'
'500':
$ref: '#/components/responses/InternalError'
/api/v2/offers/build:
post:
tags:
- Offer Endpoints
summary: Build a criteria offer
description: Build a portion of a criteria offer including the consideration item, zone, and zone hash needed to post an offer. For trait offers on supported collections, the identifierOrCriteria in the returned consideration will be '0' (no merkle root computation needed). For other collections, a computed merkle root is returned. When identifierOrCriteria is '0', the encodedTokenIds field is informational only and not required for constructing the onchain order.
operationId: build_offer_v2
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BuildOfferRequest'
required: true
responses:
'200':
description: Criteria offer built successfully
content:
'*/*':
schema:
$ref: '#/components/schemas/BuildOfferResponse'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalError'
/api/v2/offers/collection/{slug}:
get:
tags:
- Offer Endpoints
summary: Get offers by collection
description: Get collection offers on a collection.
operationId: get_offers_collection
parameters:
- name: slug
in: path
description: Unique string to identify a collection on OpenSea
required: true
schema:
type: string
- name: limit
in: query
description: Number of items to return per page
required: false
schema:
type: integer
format: int32
description: Number of items to return per page
example: 20
maximum: 200
minimum: 1
example: 20
- name: next.value
in: query
required: false
schema:
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/OffersResponse'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
/api/v2/offers/collection/{slug}/traits:
get:
tags:
- Offer Endpoints
summary: Get trait offers for a collection
description: 'Get trait offers for a collection. Use the `mode` parameter to select the bid category.
**Single string trait:** `?mode=STRING&type=Background&value=Red`
**Multiple string traits:** `?mode=MULTI&traits=[{"traitType":"Background","value":"Red"},{"traitType":"Eyes","value":"Blue"}]`
**Numeric trait range:** `?mode=NUMERIC&type=Level&min_value=1&max_value=10`
Omit filter params to discover all bids of that mode (e.g. `?mode=NUMERIC` returns all numeric bids).
If `mode` is omitted, the mode is inferred from the params for backward compatibility.'
operationId: get_offers_collection_trait
parameters:
- name: slug
in: path
description: Unique string to identify a collection on OpenSea
required: true
schema:
type: string
- name: mode
in: query
description: 'Bid category: STRING (single string trait), MULTI (multiple string traits), or NUMERIC (numeric trait range). If omitted, inferred from params.'
required: false
schema:
type: string
enum:
- STRING
- NUMERIC
- MULTI
- name: type
in: query
description: Trait type name
required: false
schema:
type: string
- name: value
in: query
description: Trait value as string
required: false
schema:
type: string
- name: float_value
in: query
description: Trait value as float
required: false
schema:
type: number
format: double
- name: int_value
in: query
description: Trait value as integer
required: false
schema:
type: integer
format: int32
- name: min_value
in: query
description: Minimum value for numeric trait range queries
required: false
schema:
type: number
format: float
- name: max_value
in: query
description: Maximum value for numeric trait range queries
required: false
schema:
type: number
format: float
- name: traits
in: query
description: 'JSON array of trait filters for multi-trait queries. Each element has ''traitType'' and ''value'' fields. Example: [{"traitType":"Background","value":"Red"}]'
required: false
schema:
type: string
example:
- traitType: Background
value: Red
- name: limit
in: query
description: Number of items to return per page
required: false
schema:
type: integer
format: int32
description: Number of items to return per page
example: 20
maximum: 200
minimum: 1
example: 20
- name: next.value
in: query
required: false
schema:
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/OffersResponse'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
/api/v2/offers/collection/{slug}/nfts/{identifier}:
get:
tags:
- Offer Endpoints
summary: Get offers by NFT
description: Get offers for an NFT.
operationId: get_offers_nft
parameters:
- name: slug
in: path
description: Unique string to identify a collection on OpenSea
required: true
schema:
type: string
- name: identifier
in: path
description: NFT token id
required: true
schema:
type: string
- name: limit
in: query
description: Number of items to return per page
required: false
schema:
type: integer
format: int32
description: Number of items to return per page
example: 20
maximum: 200
minimum: 1
example: 20
- name: next.value
in: query
required: false
schema:
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/OffersResponse'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
/api/v2/offers/collection/{slug}/nfts/{identifier}/best:
get:
tags:
- Offer Endpoints
summary: Get best offer by NFT
description: Get the best offer for an NFT.
operationId: get_best_offer_nft
parameters:
- name: slug
in: path
description: Unique string to identify a collection on OpenSea
required: true
schema:
type: string
- name: identifier
in: path
description: NFT token id
required: true
schema:
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/Offer'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
/api/v2/offers/collection/{slug}/all:
get:
tags:
- Offer Endpoints
summary: Get all offers by collection
description: Get all offers for a collection.
operationId: list_offers_collection_all
parameters:
- name: slug
in: path
description: Unique string to identify a collection on OpenSea
required: true
schema:
type: string
- name: maker
in: query
description: Filter by the wallet address of the order maker
required: false
schema:
type: string
- name: limit
in: query
description: Number of items to return per page
required: false
schema:
type: integer
format: int32
description: Number of items to return per page
example: 20
maximum: 200
minimum: 1
example: 20
- name: next.value
in: query
required: false
schema:
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/OffersResponse'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
components:
schemas:
FulfillmentComponent:
type: object
properties:
value:
type: array
items:
$ref: '#/components/schemas/Type'
orderIndex:
type: integer
itemIndex:
type: integer
typeAsString:
type: string
nativeValueCopy:
type: array
items: {}
Offer:
allOf:
- $ref: '#/components/schemas/ListingOrOffer'
- type: object
properties:
order_hash:
type: string
chain:
type: string
protocol_data:
$ref: '#/components/schemas/ProtocolData'
protocol_address:
type: string
asset:
$ref: '#/components/schemas/OrderAsset'
remaining_quantity:
type: integer
format: int64
order_created_at:
type: integer
format: int64
criteria:
$ref: '#/components/schemas/Criteria'
price:
$ref: '#/components/schemas/Price'
status:
type: string
enum:
- ACTIVE
- INACTIVE
- FULFILLED
- EXPIRED
- CANCELLED
required:
- chain
- order_hash
- price
- remaining_quantity
- status
BuildOfferRequest:
type: object
properties:
offerer:
type: string
quantity:
type: integer
format: int32
criteria:
$ref: '#/components/schemas/CriteriaObject'
protocol_address:
type: string
offer_protection_enabled:
type: boolean
required:
- criteria
- offer_protection_enabled
- offerer
- protocol_address
- quantity
AdditionalRecipient:
type: object
properties:
value:
type: array
items:
$ref: '#/components/schemas/Type'
amount:
type: integer
recipient:
type: string
typeAsString:
type: string
nativeValueCopy:
type: array
items: {}
MatchAdvancedOrders:
allOf:
- $ref: '#/components/schemas/SeaportCall'
- type: object
properties:
orders:
type: array
items:
$ref: '#/components/schemas/AdvancedOrder'
criteriaResolvers:
type: array
items:
$ref: '#/components/schemas/CriteriaResolver'
fulfillments:
type: array
items:
$ref: '#/components/schemas/Fulfillment'
recipient:
$ref: '#/components/schemas/Address'
required:
- criteriaResolvers
- fulfillments
- orders
- recipient
TraitData:
type: object
properties:
type:
type: string
value:
type: string
required:
- type
- value
SeaportProtocolDataModel:
type: object
properties:
parameters:
$ref: '#/components/schemas/SeaportParameters'
signature:
type: string
required:
- parameters
- signature
TraitObject:
type: object
properties:
type:
type: string
value:
type: string
required:
- type
- value
SeaportRequest:
type: object
properties:
parameters:
$ref: '#/components/schemas/SeaportParameters'
protocol_address:
type: string
signature:
type: string
required:
- parameters
- protocol_address
- signature
PartialParameters:
type: object
properties:
consideration:
type: array
items:
$ref: '#/components/schemas/Consideration'
zone:
type: string
zoneHash:
type: string
required:
- consideration
- zone
- zoneHash
TraitCriteria:
type: object
properties:
type:
type: string
value:
type: string
required:
- type
- value
FulfillAdvancedOrder:
allOf:
- $ref: '#/components/schemas/SeaportCall'
- type: object
properties:
advancedOrder:
$ref: '#/components/schemas/AdvancedOrder'
criteriaResolvers:
type: array
items:
$ref: '#/components/schemas/CriteriaResolver'
fulfillerConduitKey:
type: string
recipient:
$ref: '#/components/schemas/Address'
required:
- advancedOrder
- criteriaResolvers
- fulfillerConduitKey
- recipient
FulfillAvailableOrders:
allOf:
- $ref: '#/components/schemas/SeaportCall'
- type: object
properties:
orders:
type: array
items:
$ref: '#/components/schemas/Order'
offerFulfillments:
type: array
items:
type: array
items:
$ref: '#/components/schemas/FulfillmentComponent'
considerationFulfillments:
type: array
items:
type: array
items:
$ref: '#/components/schemas/FulfillmentComponent'
fulfillerConduitKey:
type: string
maximumFulfilled:
$ref: '#/components/schemas/Uint256'
required:
- considerationFulfillments
- fulfillerConduitKey
- maximumFulfilled
- offerFulfillments
- orders
OrderParameters:
type: object
properties:
value:
type: array
items:
$ref: '#/components/schemas/Type'
offerer:
type: string
zone:
type: string
offer:
type: array
items:
$ref: '#/components/schemas/OfferItem'
consideration:
type: array
items:
$ref: '#/components/schemas/ConsiderationItem'
orderType:
type: integer
startTime:
type: integer
endTime:
type: integer
zoneHash:
type: string
format: byte
salt:
type: integer
conduitKey:
type: string
format: byte
totalOriginalConsiderationItems:
type: integer
typeAsString:
type: string
nativeValueCopy:
type: array
items: {}
FulfillOrder:
allOf:
- $ref: '#/components/schemas/SeaportCall'
- type: object
properties:
order:
$ref: '#/components/schemas/Order'
fulfillerConduitKey:
type: string
required:
- fulfillerConduitKey
- order
BasicOrderParameters:
type: object
properties:
value:
type: array
items:
$ref: '#/components/schemas/Type'
considerationToken:
type: string
considerationIdentifier:
type: integer
considerationAmount:
type: integer
offerer:
type: string
zone:
type: string
offerToken:
type: string
offerIdentifier:
type: integer
offerAmount:
type: integer
basicOrderType:
type: integer
startTime:
type: integer
endTime:
type: integer
zoneHash:
type: string
format: byte
salt:
type: integer
offererConduitKey:
type: string
format: byte
fulfillerConduitKey:
type: string
format: byte
totalOriginalAdditionalRecipients:
type: integer
additionalRecipients:
type: array
items:
$ref: '#/components/schemas/AdditionalRecipient'
signature:
type: string
format: byte
typeAsString:
type: string
nativeValueCopy:
type: array
items: {}
ContractInner:
type: object
properties:
address:
type: string
required:
- address
OrderData:
type: object
properties:
parameters:
$ref: '#/components/schemas/Parameters'
signature:
type: string
required:
- parameters
- signature
OffersResponse:
type: object
properties:
offers:
type: array
items:
$ref: '#/components/schemas/Offer'
next:
type: string
required:
- offers
CriteriaObject:
type: object
properties:
collection:
$ref: '#/components/schemas/CollectionObject'
trait:
$ref: '#/components/schemas/TraitObject'
deprecated: true
description: 'Deprecated: Use ''traits'' array instead which supports both single and multiple traits.'
traits:
type: array
items:
$ref: '#/components/schemas/TraitObject'
numericTraits:
type: array
items:
$ref: '#/components/schemas/NumericTraitCriteria'
required:
- collection
FulfillmentData:
type: object
properties:
transaction:
$ref: '#/components/schemas/TransactionData'
orders:
type: array
items:
$ref: '#/components/schemas/OrderData'
required:
- orders
- transaction
ContractCriteria:
type: object
properties:
address:
type: string
required:
- address
CollectionInner:
type: object
properties:
slug:
type: string
required:
- slug
TransactionData:
type: object
properties:
function:
type: string
chain:
type: integer
format: int32
to:
type: string
value:
type: string
input_data:
oneOf:
- $ref: '#/components/schemas/FulfillAdvancedOrder'
- $ref: '#/components/schemas/FulfillAvailableAdvancedOrders'
- $ref: '#/components/schemas/FulfillAvailableOrders'
- $ref: '#/components/schemas/FulfillBasicOrder'
- $ref: '#/components/schemas/FulfillOrder'
- $ref: '#/components/schemas/MatchAdvancedOrders'
- $ref: '#/components/schemas/MatchOrders'
required:
- chain
- function
- input_data
- to
- value
OfferWithCriteriaRequest:
type: object
properties:
protocol_data:
$ref: '#/components/schemas/SeaportProtocolDataModel'
criteria:
$ref: '#/components/schemas/CriteriaRequest'
protocol_address:
type: string
required:
- criteria
- protocol_address
- protocol_data
CollectionObject:
type: object
properties:
slug:
type: string
required:
- slug
SeaportParameters:
type: object
properties:
offerer:
type: string
zone:
type: string
offer:
type: array
items:
$ref: '#/components/schemas/OfferItem'
consideration:
type: array
items:
$ref: '#/components/schemas/ConsiderationItem'
orderType:
type: integer
format: int32
startTime:
type: string
endTime:
type: string
zoneHash:
type: string
salt:
type: string
conduitKey:
type: string
totalOriginalConsiderationItems:
type: integer
format: int32
counter:
type: string
required:
- conduitKey
- consideration
- counter
- endTime
- offer
- offerer
- orderType
- salt
- startTime
- totalOriginalConsiderationItems
- zoneHash
NumericTraitCriteria:
type: object
properties:
type:
type: string
min:
type: number
format: double
max:
type: number
format: double
required:
- type
ProtocolData:
type: object
properties:
parameters:
$ref: '#/components/schemas/Parameters'
signature:
type: string
required:
- parameters
SeaportCall: {}
CriteriaResolver:
type: object
properties:
value:
type: array
items:
$ref: '#/components/schemas/Type'
orderIndex:
type: integer
side:
type: integer
index:
type: integer
identifier:
type: integer
criteriaProof:
type: array
items:
type: string
format: byte
typeAsString:
type: string
nativeValueCopy:
type: array
items: {}
Order:
type: object
properties:
order_hash:
type: string
chain:
type: string
protocol_data:
$ref: '#/components/schemas/ProtocolData'
protocol_address:
type: string
asset:
$ref: '#/components/schemas/OrderAsset'
remaining_quantity:
type: integer
format: int64
order_created_at:
type: integer
format: int64
required:
- chain
- order_hash
- remaining_quantity
CriteriaRequest:
type: object
description: Criteria for collection or trait offers. When traits are specified, the offer targets NFTs matching those traits. For supported collections, the identifierOrCriteria (merkle root) will be '0' and trait matching is validated server-side at fulfillment time.
properties:
collection:
$ref: '#/components/schemas/CollectionCriteria'
contract:
$ref: '#/components/schemas/ContractCriteria'
trait:
$ref: '#/components/schemas/TraitCriteria'
deprecated: true
description: 'Deprecated: Use ''traits'' array instead which supports both single and multiple traits.'
traits:
type: array
description: Trait criteria for the offer. Each trait specifies a type and value that target NFTs must match. These traits are validated server-side at fulfillment time.
items:
$ref: '#/components/schemas/TraitCriteria'
numericTraits:
type: array
description: Numeric trait criteria for the offer. Each entry specifies a trait type with optional min/max range bounds. Can be combined with categorical traits.
items:
$ref: '#/components/schemas/NumericTraitCriteria'
required:
- collection
Item:
type: object
properties:
itemType:
type: integer
format: int32
token:
type: string
identifierOrCriteria:
type: string
startAmount:
type: string
endAmount:
type: string
required:
- endAmount
- identifierOrCriteria
- itemType
- startAmount
- token
Type:
type: object
properties:
value: {}
typeAsString:
type: string
Address:
type: object
properties:
value:
type: string
typeAsString:
type: string
FulfillListingResponse:
type: object
properties:
protocol:
type: string
fulfillment_data:
$ref: '#/components/schemas/FulfillmentData'
required:
- fulfillment_data
- protocol
FullfillmentDataRequest:
type: object
properties:
offer:
$ref: '#/components/schemas/OfferObject'
fulfiller:
$ref: '#/components/schemas/FulfillerObject'
consideration:
$ref: '#/components/schemas/ConsiderationObject'
units_to_fill:
type: integer
format: int64
description: Optional quantity of units to fulfill; defaults to 1 for offers
include_optional_creator_fees:
type: boolean
default: false
description: Whether to include optional creator fees in the fulfillment. If creator fees are already required, this is a no-op. Defaults to false.
required:
- fulfiller
- offer
ConsiderationItem:
type: object
properties:
itemType:
type: integer
format: int32
token:
type: string
identifierOrCriteria:
type: string
startAmount:
type: string
endAmount:
type: string
recipient:
type: string
required:
- endAmount
- identifierOrCriteria
- itemType
- recipient
- startAmount
- token
BuildOfferResponse:
type: object
properties:
partialParameters:
$ref: '#/components/schemas/PartialParameters'
criteria:
$ref: '#/components/schemas/CriteriaRequest'
description: The criteria to pass through to the POST /api/v2/offers submit step. Includes collection and trait information so trait offers are not accidentally submitted as collection offers.
encodedTokenIds:
type: string
description: Encoded token IDs that can be used to fulfill the criteria offer. When identifierOrCriteria is '0', this field is informational only and not required for order construction.
required:
- criteria
- partialParameters
OfferItem:
type: object
properties:
itemType:
type: integer
format: int32
token:
type: string
identifierOrCriteria:
type: string
startAmount:
type: string
endAmount:
type: string
required:
- endAmount
- identifierOrCriteria
- itemType
- startAmount
- token
ListingOrOffer: {}
ConsiderationObject:
type: object
properties:
asset_contract_address:
type: string
token_id:
type: string
required:
- asset_contract_address
- token_id
FulfillAvailableAdvancedOrders:
allOf:
- $ref: '#/components/schemas/SeaportCall'
- type: object
properties:
orders:
type: array
items:
$ref: '#/components/schemas/AdvancedOrder'
criteriaResolvers:
type: array
items:
$ref: '#/components/schemas/CriteriaResolver'
offerFulfillments:
type: array
items:
type: array
items:
$ref: '#/components/schemas/FulfillmentComponent'
considerationFulfillments:
type: array
items:
type: array
items:
$ref: '#/components/schemas/FulfillmentComponent'
fulfillerConduitKey:
type: string
recipient:
$ref: '#/components/schemas/Address'
maximumFulfilled:
$
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/opensea/refs/heads/main/openapi/opensea-offer-endpoints-api-openapi.yml