Skip to content

Commit fb4dd20

Browse files
natsabarinatsabari
authored
Merge pull request #182 from spacescan-io/sabari
Added new DID nfts API
2 parents 4cece1c + 751aba9 commit fb4dd20

File tree

2 files changed

+327
-0
lines changed

2 files changed

+327
-0
lines changed

‎api/did/nfts.md

Lines changed: 326 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,326 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
import Tabs from '@theme/Tabs';
5+
import TabItem from '@theme/TabItem';
6+
import CodeBlock from '@theme/CodeBlock';
7+
import ApiCallExample from '@site/src/components/ApiCallExample';
8+
9+
# Get DID NFTs
10+
11+
This endpoint allows you to fetch NFTs associated with a specific DID (Decentralized Identifier), including both created and owned NFTs.
12+
13+
### Endpoint
14+
15+
<Tabs>
16+
<TabItem value="mainnet" label="Mainnet">
17+
18+
```
19+
GET https://api.spacescan.io/did/nfts/{did}
20+
```
21+
22+
</TabItem>
23+
<TabItem value="testnet" label="Testnet">
24+
25+
```
26+
GET https://api-testnet11.spacescan.io/did/nfts/{did}
27+
```
28+
29+
</TabItem>
30+
</Tabs>
31+
32+
### Parameters
33+
34+
| Parameter | Type | Required | Default | Description |
35+
|-----------|---------|----------|---------|-------------------------------------------------|
36+
| did | string | Yes | - | The Decentralized Identifier (DID) |
37+
| type | string | No | owned | Type of NFTs to fetch: `all`, `created`, `owned` |
38+
| simple | boolean | No | false | When true, returns only basic NFT info to reduce response size and improve performance |
39+
| page | number | No | 1 | Page number for pagination |
40+
| count | number | No | 100 | Number of NFTs per page (max: 100) |
41+
42+
:::info Free API
43+
Use `api.spacescan.io` for free tier access. See our [API Plans](https://spacescan.io/apis#plans) for rate limits and features.
44+
:::
45+
46+
:::tip Pro API
47+
Use `pro-api.spacescan.io` with your API key in the `x-api-key` header. See our [API Plans](https://spacescan.io/apis#plans) for details.
48+
49+
```bash
50+
curl -X GET "https://pro-api.spacescan.io/did/nfts/{did}" \
51+
-H "x-api-key: YOUR_API_KEY"
52+
```
53+
:::
54+
55+
### Live API Test
56+
57+
<Tabs>
58+
<TabItem value="mainnet" label="Mainnet">
59+
<a href="https://api.spacescan.io/did/nfts/did:chia:19qf3g9876t0rkq7tfdkc28cxfy424yzanea29rkzylq89kped9hq3q7wd2?type=owned&simple=true" target="_blank" rel="noopener noreferrer" className="api-test-button">
60+
🚀 Test API in Browser
61+
</a>
62+
</TabItem>
63+
<TabItem value="testnet" label="Testnet">
64+
<a href="https://api-testnet11.spacescan.io/did/nfts/did:chia:19qf3g9876t0rkq7tfdkc28cxfy424yzanea29rkzylq89kped9hq3q7wd2?type=owned&simple=true" target="_blank" rel="noopener noreferrer" className="api-test-button">
65+
🚀 Test API in Browser
66+
</a>
67+
</TabItem>
68+
</Tabs>
69+
70+
### Request Examples
71+
72+
<Tabs>
73+
<TabItem value="curl" label="cURL">
74+
<Tabs>
75+
<TabItem value="owned" label="Owned NFTs">
76+
<CodeBlock language="bash">
77+
curl -X GET "https://api.spacescan.io/did/nfts/did:chia:19qf3g9876t0rkq7tfdkc28cxfy424yzanea29rkzylq89kped9hq3q7wd2?type=owned&page=1&count=50"
78+
</CodeBlock>
79+
</TabItem>
80+
<TabItem value="created" label="Created NFTs">
81+
<CodeBlock language="bash">
82+
curl -X GET "https://api.spacescan.io/did/nfts/did:chia:19qf3g9876t0rkq7tfdkc28cxfy424yzanea29rkzylq89kped9hq3q7wd2?type=created&page=1&count=50"
83+
</CodeBlock>
84+
</TabItem>
85+
<TabItem value="all" label="All NFTs">
86+
<CodeBlock language="bash">
87+
curl -X GET "https://api.spacescan.io/did/nfts/did:chia:19qf3g9876t0rkq7tfdkc28cxfy424yzanea29rkzylq89kped9hq3q7wd2?type=all&page=1&count=50"
88+
</CodeBlock>
89+
</TabItem>
90+
<TabItem value="simple" label="Simple Mode">
91+
<CodeBlock language="bash">
92+
curl -X GET "https://api.spacescan.io/did/nfts/did:chia:19qf3g9876t0rkq7tfdkc28cxfy424yzanea29rkzylq89kped9hq3q7wd2?type=owned&simple=true&page=1&count=50"
93+
</CodeBlock>
94+
</TabItem>
95+
</Tabs>
96+
</TabItem>
97+
<TabItem value="python" label="Python">
98+
<Tabs>
99+
<TabItem value="owned" label="Owned NFTs">
100+
<CodeBlock language="python">
101+
{`import requests
102+
103+
did = "did:chia:19qf3g9876t0rkq7tfdkc28cxfy424yzanea29rkzylq89kped9hq3q7wd2"
104+
params = {
105+
"type": "owned",
106+
"page": 1,
107+
"count": 50
108+
}
109+
url = f"https://api.spacescan.io/did/nfts/{did}"
110+
111+
response = requests.get(url, params=params)
112+
data = response.json()
113+
print(data)`}
114+
</CodeBlock>
115+
</TabItem>
116+
<TabItem value="simple" label="Simple Mode">
117+
<CodeBlock language="python">
118+
{`import requests
119+
120+
did = "did:chia:19qf3g9876t0rkq7tfdkc28cxfy424yzanea29rkzylq89kped9hq3q7wd2"
121+
params = {
122+
"type": "owned",
123+
"simple": True,
124+
"page": 1,
125+
"count": 50
126+
}
127+
url = f"https://api.spacescan.io/did/nfts/{did}"
128+
129+
response = requests.get(url, params=params)
130+
data = response.json()
131+
print(data)`}
132+
</CodeBlock>
133+
</TabItem>
134+
</Tabs>
135+
</TabItem>
136+
<TabItem value="javascript" label="JavaScript">
137+
<Tabs>
138+
<TabItem value="owned" label="Owned NFTs">
139+
<CodeBlock language="javascript">
140+
{`const did = "did:chia:19qf3g9876t0rkq7tfdkc28cxfy424yzanea29rkzylq89kped9hq3q7wd2";
141+
const params = new URLSearchParams({
142+
type: "owned",
143+
page: "1",
144+
count: "50"
145+
});
146+
const url = \`https://api.spacescan.io/did/nfts/\${did}?\${params}\`;
147+
148+
fetch(url)
149+
.then(response => response.json())
150+
.then(data => console.log(data))
151+
.catch(error => console.error('Error:', error));`}
152+
</CodeBlock>
153+
</TabItem>
154+
<TabItem value="simple" label="Simple Mode">
155+
<CodeBlock language="javascript">
156+
{`const did = "did:chia:19qf3g9876t0rkq7tfdkc28cxfy424yzanea29rkzylq89kped9hq3q7wd2";
157+
const params = new URLSearchParams({
158+
type: "owned",
159+
simple: "true",
160+
page: "1",
161+
count: "50"
162+
});
163+
const url = \`https://api.spacescan.io/did/nfts/\${did}?\${params}\`;
164+
165+
fetch(url)
166+
.then(response => response.json())
167+
.then(data => console.log(data))
168+
.catch(error => console.error('Error:', error));`}
169+
</CodeBlock>
170+
</TabItem>
171+
</Tabs>
172+
</TabItem>
173+
</Tabs>
174+
175+
### Response
176+
177+
<Tabs>
178+
<TabItem value="mainnet" label="Mainnet">
179+
<ApiCallExample endpoint="https://api.spacescan.io/did/nfts/did:chia:19qf3g9876t0rkq7tfdkc28cxfy424yzanea29rkzylq89kped9hq3q7wd2?type=owned&simple=true&page=1&count=5" />
180+
</TabItem>
181+
<TabItem value="testnet" label="Testnet">
182+
<ApiCallExample endpoint="https://api-testnet11.spacescan.io/did/nfts/did:chia:19qf3g9876t0rkq7tfdkc28cxfy424yzanea29rkzylq89kped9hq3q7wd2?type=owned&simple=true&page=1&count=5" />
183+
</TabItem>
184+
</Tabs>
185+
186+
### Response Schema
187+
188+
| Field | Type | Description |
189+
|-------------------------|---------|-------------------------------------------------------|
190+
| status | string | The status of the API request |
191+
| data | object | The main data object |
192+
| data.owned_nft_count | number | Total number of NFTs owned by the DID |
193+
| data.created_nft_count | number | Total number of NFTs created by the DID |
194+
| data.page | number | Current page number |
195+
| data.size | number | Number of NFTs per page |
196+
| data.owned_nfts | array | Array of owned NFTs (when type is 'owned' or 'all') |
197+
| data.created_nfts | array | Array of created NFTs (when type is 'created' or 'all') |
198+
199+
### NFT Object Schema (Full Mode)
200+
201+
| Field | Type | Description |
202+
|-------------------------|---------|-------------------------------------------------------|
203+
| id | string | The NFT ID |
204+
| name | string | The NFT name |
205+
| preview_url | string | URL to the NFT preview image |
206+
| created_height | string | Block height when NFT was created |
207+
| created_time | string | Timestamp when NFT was created |
208+
| flagged | boolean | Whether the NFT has been flagged |
209+
| description | string | NFT description |
210+
| collection | object | Collection information |
211+
| collection.id | string | Collection ID |
212+
| collection.name | string | Collection name |
213+
| last_sale | string | Last sale price in mojos |
214+
| creator | object | Creator information |
215+
| creator.address | string | Creator's address |
216+
| creator.address_hex | string | Creator's address in hex format |
217+
| creator.did | string | Creator's DID |
218+
| creator.did_hex | string | Creator's DID in hex format |
219+
| owner | object | Owner information |
220+
| owner.address | string | Owner's address |
221+
| owner.address_hex | string | Owner's address in hex format |
222+
| sensitive_content | boolean | Whether the NFT contains sensitive content |
223+
| attributes | array | NFT attributes |
224+
| rarity | number | NFT rarity score |
225+
| top_bid | number | Current top bid price |
226+
| buy_now | number | Buy now price |
227+
228+
### NFT Object Schema (Simple Mode)
229+
230+
| Field | Type | Description |
231+
|-------------------------|---------|-------------------------------------------------------|
232+
| id | string | The NFT ID |
233+
| name | string | The NFT name |
234+
| preview_url | string | URL to the NFT preview image |
235+
| collection | object | Collection information |
236+
| collection.id | string | Collection ID |
237+
| collection.name | string | Collection name |
238+
239+
### Type Parameter Options
240+
241+
- **`owned`** (default): Returns only NFTs currently owned by the DID
242+
- **`created`**: Returns only NFTs created by the DID
243+
- **`all`**: Returns both owned and created NFTs
244+
245+
### Simple Mode Benefits
246+
247+
When `simple=true` is used:
248+
- **Reduced Response Size**: Only essential fields are included
249+
- **Faster Performance**: Less data processing and transfer
250+
- **Lower Bandwidth**: Ideal for mobile applications or when only basic info is needed
251+
- **Better Caching**: Smaller responses can be cached more efficiently
252+
253+
### Example Responses
254+
255+
<Tabs>
256+
<TabItem value="full" label="Full Mode Response">
257+
<CodeBlock language="json">
258+
{`{
259+
"status": "success",
260+
"data": {
261+
"owned_nft_count": 25,
262+
"created_nft_count": 10,
263+
"page": 1,
264+
"size": 50,
265+
"owned_nfts": [
266+
{
267+
"id": "nft1abc123def456",
268+
"name": "Cool NFT #1",
269+
"preview_url": "https://assets.spacescan.io/nft/image1.jpg",
270+
"created_height": "1234567",
271+
"created_time": "2023-01-15T10:30:00Z",
272+
"flagged": false,
273+
"description": "A really cool NFT",
274+
"collection": {
275+
"id": "col123",
276+
"name": "Cool Collection"
277+
},
278+
"last_sale": "1000000",
279+
"creator": {
280+
"address": "xch1abc...",
281+
"address_hex": "abc123...",
282+
"did": "did:chia:123...",
283+
"did_hex": "123..."
284+
},
285+
"owner": {
286+
"address": "xch1def...",
287+
"address_hex": "def456..."
288+
},
289+
"sensitive_content": false,
290+
"attributes": [],
291+
"rarity": 85,
292+
"top_bid": 500000,
293+
"buy_now": 2000000
294+
}
295+
],
296+
"created_nfts": []
297+
}
298+
}`}
299+
</CodeBlock>
300+
</TabItem>
301+
<TabItem value="simple" label="Simple Mode Response">
302+
<CodeBlock language="json">
303+
{`{
304+
"status": "success",
305+
"data": {
306+
"owned_nft_count": 25,
307+
"created_nft_count": 10,
308+
"page": 1,
309+
"size": 50,
310+
"owned_nfts": [
311+
{
312+
"id": "nft1abc123def456",
313+
"name": "Cool NFT #1",
314+
"preview_url": "https://assets.spacescan.io/nft/image1.jpg",
315+
"collection": {
316+
"id": "col123",
317+
"name": "Cool Collection"
318+
}
319+
}
320+
],
321+
"created_nfts": []
322+
}
323+
}`}
324+
</CodeBlock>
325+
</TabItem>
326+
</Tabs>

‎apisidebars.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@ const sidebars = {
7474
label: 'DID',
7575
items: [
7676
'did/info',
77+
'did/nfts',
7778
],
7879
},
7980
{

0 commit comments

Comments
 (0)