Get Offers by Asset

This endpoint allows you to fetch all offers that include a specific asset (NFT or CAT) in either their requested or offered assets.

Endpoint

Mainnet

GET https://api.spacescan.io/offers/asset/{asset_id}

Testnet

GET https://api-testnet11.spacescan.io/offers/asset/{asset_id}

Parameters

Parameter	Type	Required	Default	Description
asset_id	string	Yes	-	NFT or Token or Collection ID or XCH
count	number	No	100	Number of offers to return (max: 100)
page	number	No	1	Page number for pagination

Headers

Header	Type	Required	Description
version	string	Yes	API version
network	string	Yes	Network identifier (e.g., 'xch' for mainnet)

Free API

Use api.spacescan.io for free tier access. See our API Plans for rate limits and features.

Pro API

Use pro-api.spacescan.io with your API key in the x-api-key header. See our API Plans for details.

curl -X GET "https://pro-api.spacescan.io/offers/asset/{asset_id}?count=50&page=1" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "version: v1" \
     -H "network: xch"

Live API Test

Mainnet

🚀 Test API in Browser

Request Examples

cURL

curl -X GET "https://api.spacescan.io/offers/asset/8c77de1427156b98fb15cce77d908f79bd69f6b4b8e3a60d8e051dac481b5365" \
     -H "version: v1" \
     -H "network: xch"

Python

import requests

asset_id = "8c77de1427156b98fb15cce77d908f79bd69f6b4b8e3a60d8e051dac481b5365"
url = f"https://api.spacescan.io/offers/asset/{asset_id}"
headers = {
    "version": "v1",
    "network": "xch"
}
params = {
    "count": 50,
    "page": 1
}

response = requests.get(url, headers=headers, params=params)
data = response.json()
print(data)

JavaScript

const assetId = "8c77de1427156b98fb15cce77d908f79bd69f6b4b8e3a60d8e051dac481b5365";
const url = new URL(`https://api.spacescan.io/offers/asset/${assetId}`);
url.searchParams.append("count", "50");
url.searchParams.append("page", "1");

fetch(url, {
  headers: {
    "version": "v1",
    "network": "xch"
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Response Schema

Field	Type	Description
status	string	Status of the request ("success" or "failed")
data	array	Array of offer information objects

Each offer object in the data array has the following structure:

Field	Type	Description
id	string	The unique identifier of the offer
offer_status	string	Current status of the offer
offer	string	Raw offer data
offered	array	Array of assets being offered
requested	array	Array of assets being requested
created	string	Timestamp of offer creation
settled	string	Timestamp when offer was settled
height	number	Block height of the offer

Example Response

{
  "status": "success",
  "data": [
    {
      "id": "offer1abc...",
      "offer_status": "Active",
      "offer": "raw_offer_data",
      "offered": [
        {
          "type": "NFT1",
          "nft_info": {
            "id": "nft1...",
            "name": "Sample NFT",
            "preview_url": "https://..."
          }
        }
      ],
      "requested": [
        {
          "type": "XCH",
          "symbol": "XCH",
          "amount": 1.5
        }
      ],
      "created": "2023-01-01T00:00:00Z",
      "settled": null,
      "height": 1234567
    }
    // ... more offers
  ]
}

Error Responses

HTTP Status Code	Meaning
401	Unauthorized -- Missing required headers
400	Bad Request -- Invalid asset ID format
429	Too Many Requests -- You're requesting too many times
500	Internal Server Error -- We had a problem with our server
503	Service Unavailable -- We're temporarily offline for maintenance