@opensea/sdk 12.1.0 → 12.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -4,42 +4,68 @@ import type { Chain } from "../types"
4
4
  /** Base path prefix for all OpenSea API v2 endpoints. */
5
5
  export const API_V2_PREFIX = "/api/v2"
6
6
 
7
+ /**
8
+ * Encodes a single path segment.
9
+ *
10
+ * Every builder below interpolates caller-supplied values into a URL path. Without encoding, a
11
+ * value containing `/` re-targets the request at a different endpoint once the URL is normalized,
12
+ * and a consumer that caches by path collides with the endpoint it lands on. Encoding is a no-op
13
+ * for every legitimate value: collection slugs, hex addresses, base58 addresses, token ids and
14
+ * transaction hashes all survive `encodeURIComponent` unchanged.
15
+ *
16
+ * `.` and `..` are rejected rather than encoded, because encoding cannot neutralize them. The
17
+ * WHATWG URL parser decodes percent-escapes before it removes dot segments, so `%2E%2E` collapses
18
+ * exactly as `..` does, and there is no spelling of a bare dot segment that survives as a literal.
19
+ * No collection slug, address, token id or transaction hash is `.` or `..`, so a caller reaching
20
+ * this is passing through unvalidated input and should hear about it rather than silently request
21
+ * a different endpoint.
22
+ */
23
+ export const segment = (value: string | number) => {
24
+ const raw = String(value)
25
+ if (raw === "." || raw === "..") {
26
+ throw new RangeError(
27
+ `Invalid path segment: ${JSON.stringify(raw)} would traverse to a different endpoint`,
28
+ )
29
+ }
30
+ return encodeURIComponent(raw)
31
+ }
32
+
7
33
  export const getPostListingPath = (chain: Chain, protocol: OrderProtocol) => {
8
- return `${API_V2_PREFIX}/orders/${chain}/${protocol}/listings`
34
+ return `${API_V2_PREFIX}/orders/${segment(chain)}/${segment(protocol)}/listings`
9
35
  }
10
36
 
11
37
  export const getPostOfferPath = (chain: Chain, protocol: OrderProtocol) => {
12
- return `${API_V2_PREFIX}/orders/${chain}/${protocol}/offers`
38
+ return `${API_V2_PREFIX}/orders/${segment(chain)}/${segment(protocol)}/offers`
13
39
  }
14
40
 
15
41
  export const getAllOffersAPIPath = (collectionSlug: string) => {
16
- return `${API_V2_PREFIX}/offers/collection/${collectionSlug}/all`
42
+ return `${API_V2_PREFIX}/offers/collection/${segment(collectionSlug)}/all`
17
43
  }
18
44
 
19
45
  export const getAllListingsAPIPath = (collectionSlug: string) => {
20
- return `${API_V2_PREFIX}/listings/collection/${collectionSlug}/all`
46
+ return `${API_V2_PREFIX}/listings/collection/${segment(collectionSlug)}/all`
21
47
  }
22
48
 
23
49
  export const getBestOfferAPIPath = (
24
50
  collectionSlug: string,
25
51
  tokenId: string | number,
26
52
  ) => {
27
- return `${API_V2_PREFIX}/offers/collection/${collectionSlug}/nfts/${tokenId}/best`
53
+ return `${API_V2_PREFIX}/offers/collection/${segment(collectionSlug)}/nfts/${segment(tokenId)}/best`
28
54
  }
29
55
 
30
56
  export const getBestListingAPIPath = (
31
57
  collectionSlug: string,
32
58
  tokenId: string | number,
33
59
  ) => {
34
- return `${API_V2_PREFIX}/listings/collection/${collectionSlug}/nfts/${tokenId}/best`
60
+ return `${API_V2_PREFIX}/listings/collection/${segment(collectionSlug)}/nfts/${segment(tokenId)}/best`
35
61
  }
36
62
 
37
63
  export const getBestListingsAPIPath = (collectionSlug: string) => {
38
- return `${API_V2_PREFIX}/listings/collection/${collectionSlug}/best`
64
+ return `${API_V2_PREFIX}/listings/collection/${segment(collectionSlug)}/best`
39
65
  }
40
66
 
41
67
  export const getCollectionPath = (slug: string) => {
42
- return `${API_V2_PREFIX}/collections/${slug}`
68
+ return `${API_V2_PREFIX}/collections/${segment(slug)}`
43
69
  }
44
70
 
45
71
  export const getCollectionsPath = () => {
@@ -47,19 +73,19 @@ export const getCollectionsPath = () => {
47
73
  }
48
74
 
49
75
  export const getCollectionStatsPath = (slug: string) => {
50
- return `${API_V2_PREFIX}/collections/${slug}/stats`
76
+ return `${API_V2_PREFIX}/collections/${segment(slug)}/stats`
51
77
  }
52
78
 
53
79
  export const getPaymentTokenPath = (chain: Chain, address: string) => {
54
- return `${API_V2_PREFIX}/chain/${chain}/payment_token/${address}`
80
+ return `${API_V2_PREFIX}/chain/${segment(chain)}/payment_token/${segment(address)}`
55
81
  }
56
82
 
57
83
  export const getAccountPath = (address: string) => {
58
- return `${API_V2_PREFIX}/accounts/${address}`
84
+ return `${API_V2_PREFIX}/accounts/${segment(address)}`
59
85
  }
60
86
 
61
87
  export const getAgentProfileRelationshipsPath = (addressOrUsername: string) => {
62
- return `${API_V2_PREFIX}/accounts/${addressOrUsername}/agent-relationships`
88
+ return `${API_V2_PREFIX}/accounts/${segment(addressOrUsername)}/agent-relationships`
63
89
  }
64
90
 
65
91
  export const getBuildOfferPath = () => {
@@ -71,19 +97,19 @@ export const getPostCollectionOfferPath = () => {
71
97
  }
72
98
 
73
99
  export const getCollectionOffersPath = (slug: string) => {
74
- return `${API_V2_PREFIX}/offers/collection/${slug}`
100
+ return `${API_V2_PREFIX}/offers/collection/${segment(slug)}`
75
101
  }
76
102
 
77
103
  export const getListNFTsByCollectionPath = (slug: string) => {
78
- return `${API_V2_PREFIX}/collection/${slug}/nfts`
104
+ return `${API_V2_PREFIX}/collection/${segment(slug)}/nfts`
79
105
  }
80
106
 
81
107
  export const getListNFTsByContractPath = (chain: Chain, address: string) => {
82
- return `${API_V2_PREFIX}/chain/${chain}/contract/${address}/nfts`
108
+ return `${API_V2_PREFIX}/chain/${segment(chain)}/contract/${segment(address)}/nfts`
83
109
  }
84
110
 
85
111
  export const getListNFTsByAccountPath = (chain: Chain, address: string) => {
86
- return `${API_V2_PREFIX}/chain/${chain}/account/${address}/nfts`
112
+ return `${API_V2_PREFIX}/chain/${segment(chain)}/account/${segment(address)}/nfts`
87
113
  }
88
114
 
89
115
  export const getNFTPath = (
@@ -91,7 +117,7 @@ export const getNFTPath = (
91
117
  address: string,
92
118
  identifier: string,
93
119
  ) => {
94
- return `${API_V2_PREFIX}/chain/${chain}/contract/${address}/nfts/${identifier}`
120
+ return `${API_V2_PREFIX}/chain/${segment(chain)}/contract/${segment(address)}/nfts/${segment(identifier)}`
95
121
  }
96
122
 
97
123
  export const getRefreshMetadataPath = (
@@ -99,7 +125,7 @@ export const getRefreshMetadataPath = (
99
125
  address: string,
100
126
  identifier: string,
101
127
  ) => {
102
- return `${API_V2_PREFIX}/chain/${chain}/contract/${address}/nfts/${identifier}/refresh`
128
+ return `${API_V2_PREFIX}/chain/${segment(chain)}/contract/${segment(address)}/nfts/${segment(identifier)}/refresh`
103
129
  }
104
130
 
105
131
  export const getOrderByHashPath = (
@@ -107,7 +133,7 @@ export const getOrderByHashPath = (
107
133
  protocolAddress: string,
108
134
  orderHash: string,
109
135
  ) => {
110
- return `${API_V2_PREFIX}/orders/chain/${chain}/protocol/${protocolAddress}/${orderHash}`
136
+ return `${API_V2_PREFIX}/orders/chain/${segment(chain)}/protocol/${segment(protocolAddress)}/${segment(orderHash)}`
111
137
  }
112
138
 
113
139
  export const getCancelOrderPath = (
@@ -115,7 +141,7 @@ export const getCancelOrderPath = (
115
141
  protocolAddress: string,
116
142
  orderHash: string,
117
143
  ) => {
118
- return `${API_V2_PREFIX}/orders/chain/${chain}/protocol/${protocolAddress}/${orderHash}/cancel`
144
+ return `${API_V2_PREFIX}/orders/chain/${segment(chain)}/protocol/${segment(protocolAddress)}/${segment(orderHash)}/cancel`
119
145
  }
120
146
 
121
147
  export const getCreateCancelOrderActionsPath = (
@@ -123,7 +149,7 @@ export const getCreateCancelOrderActionsPath = (
123
149
  protocolAddress: string,
124
150
  orderIdentifier: string,
125
151
  ) => {
126
- return `${API_V2_PREFIX}/orders/chain/${chain}/protocol/${protocolAddress}/${orderIdentifier}/cancel/actions`
152
+ return `${API_V2_PREFIX}/orders/chain/${segment(chain)}/protocol/${segment(protocolAddress)}/${segment(orderIdentifier)}/cancel/actions`
127
153
  }
128
154
 
129
155
  export const getCreateListingFulfillmentActionsPath = () => {
@@ -139,14 +165,14 @@ export const getCreateOfferFulfillmentActionsPath = () => {
139
165
  }
140
166
 
141
167
  export const getTraitOffersPath = (collectionSlug: string) => {
142
- return `${API_V2_PREFIX}/offers/collection/${collectionSlug}/traits`
168
+ return `${API_V2_PREFIX}/offers/collection/${segment(collectionSlug)}/traits`
143
169
  }
144
170
 
145
171
  export const getOffersByNFTPath = (
146
172
  collectionSlug: string,
147
173
  identifier: string | number,
148
174
  ) => {
149
- return `${API_V2_PREFIX}/offers/collection/${collectionSlug}/nfts/${identifier}`
175
+ return `${API_V2_PREFIX}/offers/collection/${segment(collectionSlug)}/nfts/${segment(identifier)}`
150
176
  }
151
177
 
152
178
  export const getSweepListingsPath = () => {
@@ -166,11 +192,11 @@ export const getEventsAPIPath = () => {
166
192
  }
167
193
 
168
194
  export const getEventsByAccountAPIPath = (address: string) => {
169
- return `${API_V2_PREFIX}/events/accounts/${address}`
195
+ return `${API_V2_PREFIX}/events/accounts/${segment(address)}`
170
196
  }
171
197
 
172
198
  export const getEventsByCollectionAPIPath = (collectionSlug: string) => {
173
- return `${API_V2_PREFIX}/events/collection/${collectionSlug}`
199
+ return `${API_V2_PREFIX}/events/collection/${segment(collectionSlug)}`
174
200
  }
175
201
 
176
202
  export const getEventsByNFTAPIPath = (
@@ -178,15 +204,19 @@ export const getEventsByNFTAPIPath = (
178
204
  address: string,
179
205
  identifier: string,
180
206
  ) => {
181
- return `${API_V2_PREFIX}/events/chain/${chain}/contract/${address}/nfts/${identifier}`
207
+ return `${API_V2_PREFIX}/events/chain/${segment(chain)}/contract/${segment(address)}/nfts/${segment(identifier)}`
182
208
  }
183
209
 
184
210
  export const getContractPath = (chain: Chain, address: string) => {
185
- return `${API_V2_PREFIX}/chain/${chain}/contract/${address}`
211
+ return `${API_V2_PREFIX}/chain/${segment(chain)}/contract/${segment(address)}`
186
212
  }
187
213
 
188
214
  export const getTraitsPath = (collectionSlug: string) => {
189
- return `${API_V2_PREFIX}/traits/${collectionSlug}`
215
+ return `${API_V2_PREFIX}/traits/${segment(collectionSlug)}`
216
+ }
217
+
218
+ export const getCollectionTraitFloorsPath = (collectionSlug: string) => {
219
+ return `${API_V2_PREFIX}/traits/${segment(collectionSlug)}/floors`
190
220
  }
191
221
 
192
222
  export const getTrendingTokensPath = () => {
@@ -202,7 +232,7 @@ export const getSwapQuotePath = () => {
202
232
  }
203
233
 
204
234
  export const getTokenPath = (chain: string, address: string) => {
205
- return `${API_V2_PREFIX}/chain/${chain}/token/${address}`
235
+ return `${API_V2_PREFIX}/chain/${segment(chain)}/token/${segment(address)}`
206
236
  }
207
237
 
208
238
  export const getSearchPath = () => {
@@ -214,7 +244,7 @@ export const getChainsPath = () => {
214
244
  }
215
245
 
216
246
  export const getAccountTokensPath = (address: string) => {
217
- return `${API_V2_PREFIX}/account/${address}/tokens`
247
+ return `${API_V2_PREFIX}/account/${segment(address)}/tokens`
218
248
  }
219
249
 
220
250
  export const getValidateMetadataPath = (
@@ -222,7 +252,7 @@ export const getValidateMetadataPath = (
222
252
  address: string,
223
253
  identifier: string,
224
254
  ) => {
225
- return `${API_V2_PREFIX}/chain/${chain}/contract/${address}/nfts/${identifier}/validate-metadata`
255
+ return `${API_V2_PREFIX}/chain/${segment(chain)}/contract/${segment(address)}/nfts/${segment(identifier)}/validate-metadata`
226
256
  }
227
257
 
228
258
  export const getDropsPath = () => {
@@ -230,15 +260,15 @@ export const getDropsPath = () => {
230
260
  }
231
261
 
232
262
  export const getDropPath = (slug: string) => {
233
- return `${API_V2_PREFIX}/drops/${slug}`
263
+ return `${API_V2_PREFIX}/drops/${segment(slug)}`
234
264
  }
235
265
 
236
266
  export const getDropMintPath = (slug: string) => {
237
- return `${API_V2_PREFIX}/drops/${slug}/mint`
267
+ return `${API_V2_PREFIX}/drops/${segment(slug)}/mint`
238
268
  }
239
269
 
240
270
  export const getCrossChainDropMintPath = (slug: string) => {
241
- return `${API_V2_PREFIX}/drops/${slug}/cross_chain_mint`
271
+ return `${API_V2_PREFIX}/drops/${segment(slug)}/cross_chain_mint`
242
272
  }
243
273
 
244
274
  export const getTrendingCollectionsPath = () => {
@@ -250,7 +280,7 @@ export const getTopCollectionsPath = () => {
250
280
  }
251
281
 
252
282
  export const getResolveAccountPath = (identifier: string) => {
253
- return `${API_V2_PREFIX}/accounts/resolve/${identifier}`
283
+ return `${API_V2_PREFIX}/accounts/resolve/${segment(identifier)}`
254
284
  }
255
285
 
256
286
  export const getNFTCollectionPath = (
@@ -258,7 +288,7 @@ export const getNFTCollectionPath = (
258
288
  address: string,
259
289
  identifier: string,
260
290
  ) => {
261
- return `${API_V2_PREFIX}/chain/${chain}/contract/${address}/nfts/${identifier}/collection`
291
+ return `${API_V2_PREFIX}/chain/${segment(chain)}/contract/${segment(address)}/nfts/${segment(identifier)}/collection`
262
292
  }
263
293
 
264
294
  export const getNFTMetadataPath = (
@@ -266,7 +296,7 @@ export const getNFTMetadataPath = (
266
296
  contractAddress: string,
267
297
  tokenId: string,
268
298
  ) => {
269
- return `${API_V2_PREFIX}/metadata/${chain}/${contractAddress}/${tokenId}`
299
+ return `${API_V2_PREFIX}/metadata/${segment(chain)}/${segment(contractAddress)}/${segment(tokenId)}`
270
300
  }
271
301
 
272
302
  export const getTokenGroupsPath = () => {
@@ -274,7 +304,7 @@ export const getTokenGroupsPath = () => {
274
304
  }
275
305
 
276
306
  export const getTokenGroupPath = (slug: string) => {
277
- return `${API_V2_PREFIX}/token-groups/${slug}`
307
+ return `${API_V2_PREFIX}/token-groups/${segment(slug)}`
278
308
  }
279
309
 
280
310
  export const getCrossChainFulfillmentDataPath = () => {
@@ -312,7 +342,7 @@ export const getDeployDropPath = () => {
312
342
  }
313
343
 
314
344
  export const getDeployDropReceiptPath = (chain: Chain, txHash: string) => {
315
- return `${API_V2_PREFIX}/drops/deploy/${chain}/${txHash}/receipt`
345
+ return `${API_V2_PREFIX}/drops/deploy/${segment(chain)}/${segment(txHash)}/receipt`
316
346
  }
317
347
 
318
348
  // ── Assets transfer ─────────────────────────────────────────────────
@@ -324,45 +354,45 @@ export const getTransferAssetsPath = () => {
324
354
  // ── Collection analytics ────────────────────────────────────────────
325
355
 
326
356
  export const getCollectionOfferAggregatesPath = (slug: string) => {
327
- return `${API_V2_PREFIX}/collections/${slug}/offer_aggregates`
357
+ return `${API_V2_PREFIX}/collections/${segment(slug)}/offer_aggregates`
328
358
  }
329
359
 
330
360
  export const getCollectionHoldersPath = (slug: string) => {
331
- return `${API_V2_PREFIX}/collections/${slug}/holders`
361
+ return `${API_V2_PREFIX}/collections/${segment(slug)}/holders`
332
362
  }
333
363
 
334
364
  export const getCollectionFloorPricesPath = (slug: string) => {
335
- return `${API_V2_PREFIX}/collections/${slug}/floor_prices`
365
+ return `${API_V2_PREFIX}/collections/${segment(slug)}/floor_prices`
336
366
  }
337
367
 
338
368
  // ── Token analytics ─────────────────────────────────────────────────
339
369
 
340
370
  export const getTokenPriceHistoryPath = (chain: Chain, address: string) => {
341
- return `${API_V2_PREFIX}/chain/${chain}/token/${address}/price_history`
371
+ return `${API_V2_PREFIX}/chain/${segment(chain)}/token/${segment(address)}/price_history`
342
372
  }
343
373
 
344
374
  export const getTokenOhlcvPath = (chain: Chain, address: string) => {
345
- return `${API_V2_PREFIX}/chain/${chain}/token/${address}/ohlcv`
375
+ return `${API_V2_PREFIX}/chain/${segment(chain)}/token/${segment(address)}/ohlcv`
346
376
  }
347
377
 
348
378
  export const getTokenActivityPath = (chain: Chain, address: string) => {
349
- return `${API_V2_PREFIX}/chain/${chain}/token/${address}/activity`
379
+ return `${API_V2_PREFIX}/chain/${segment(chain)}/token/${segment(address)}/activity`
350
380
  }
351
381
 
352
382
  export const getTokenActivityStatsPath = (chain: Chain, address: string) => {
353
- return `${API_V2_PREFIX}/chain/${chain}/token/${address}/activity/stats`
383
+ return `${API_V2_PREFIX}/chain/${segment(chain)}/token/${segment(address)}/activity/stats`
354
384
  }
355
385
 
356
386
  export const getAccountTokenActivityPath = (address: string) => {
357
- return `${API_V2_PREFIX}/account/${address}/token-activity`
387
+ return `${API_V2_PREFIX}/account/${segment(address)}/token-activity`
358
388
  }
359
389
 
360
390
  export const getTokenHoldersPath = (chain: Chain, address: string) => {
361
- return `${API_V2_PREFIX}/chain/${chain}/token/${address}/holders`
391
+ return `${API_V2_PREFIX}/chain/${segment(chain)}/token/${segment(address)}/holders`
362
392
  }
363
393
 
364
394
  export const getTokenLiquidityPoolsPath = (chain: Chain, address: string) => {
365
- return `${API_V2_PREFIX}/chain/${chain}/token/${address}/liquidity-pools`
395
+ return `${API_V2_PREFIX}/chain/${segment(chain)}/token/${segment(address)}/liquidity-pools`
366
396
  }
367
397
 
368
398
  // ── NFT analytics ───────────────────────────────────────────────────
@@ -372,7 +402,7 @@ export const getNFTOwnersPath = (
372
402
  address: string,
373
403
  identifier: string,
374
404
  ) => {
375
- return `${API_V2_PREFIX}/chain/${chain}/contract/${address}/nfts/${identifier}/owners`
405
+ return `${API_V2_PREFIX}/chain/${segment(chain)}/contract/${segment(address)}/nfts/${segment(identifier)}/owners`
376
406
  }
377
407
 
378
408
  export const getNFTAnalyticsPath = (
@@ -380,47 +410,47 @@ export const getNFTAnalyticsPath = (
380
410
  address: string,
381
411
  identifier: string,
382
412
  ) => {
383
- return `${API_V2_PREFIX}/chain/${chain}/contract/${address}/nfts/${identifier}/analytics`
413
+ return `${API_V2_PREFIX}/chain/${segment(chain)}/contract/${segment(address)}/nfts/${segment(identifier)}/analytics`
384
414
  }
385
415
 
386
416
  // ── Account portfolio / profile ─────────────────────────────────────
387
417
 
388
418
  export const getPortfolioStatsPath = (address: string) => {
389
- return `${API_V2_PREFIX}/account/${address}/portfolio`
419
+ return `${API_V2_PREFIX}/account/${segment(address)}/portfolio`
390
420
  }
391
421
 
392
422
  export const getPortfolioHistoryPath = (address: string) => {
393
- return `${API_V2_PREFIX}/account/${address}/portfolio/history`
423
+ return `${API_V2_PREFIX}/account/${segment(address)}/portfolio/history`
394
424
  }
395
425
 
396
426
  export const getProfileOffersReceivedPath = (address: string) => {
397
- return `${API_V2_PREFIX}/account/${address}/offers_received`
427
+ return `${API_V2_PREFIX}/account/${segment(address)}/offers_received`
398
428
  }
399
429
 
400
430
  export const getProfileOffersPath = (address: string) => {
401
- return `${API_V2_PREFIX}/account/${address}/offers`
431
+ return `${API_V2_PREFIX}/account/${segment(address)}/offers`
402
432
  }
403
433
 
404
434
  export const getProfileListingsPath = (address: string) => {
405
- return `${API_V2_PREFIX}/account/${address}/listings`
435
+ return `${API_V2_PREFIX}/account/${segment(address)}/listings`
406
436
  }
407
437
 
408
438
  export const getProfileFavoritesPath = (address: string) => {
409
- return `${API_V2_PREFIX}/account/${address}/favorites`
439
+ return `${API_V2_PREFIX}/account/${segment(address)}/favorites`
410
440
  }
411
441
 
412
442
  export const getWalletPnlPath = (address: string) => {
413
- return `${API_V2_PREFIX}/account/${address}/pnl`
443
+ return `${API_V2_PREFIX}/account/${segment(address)}/pnl`
414
444
  }
415
445
 
416
446
  export const getWalletClosedPositionsPath = (address: string) => {
417
- return `${API_V2_PREFIX}/account/${address}/pnl/closed-positions`
447
+ return `${API_V2_PREFIX}/account/${segment(address)}/pnl/closed-positions`
418
448
  }
419
449
 
420
450
  export const getWalletTokenTransfersPath = (address: string) => {
421
- return `${API_V2_PREFIX}/account/${address}/pnl/token-transfers`
451
+ return `${API_V2_PREFIX}/account/${segment(address)}/pnl/token-transfers`
422
452
  }
423
453
 
424
454
  export const getProfileCollectionsPath = (address: string) => {
425
- return `${API_V2_PREFIX}/account/${address}/collections`
455
+ return `${API_V2_PREFIX}/account/${segment(address)}/collections`
426
456
  }
@@ -7,6 +7,7 @@ import {
7
7
  getCollectionPath,
8
8
  getCollectionStatsPath,
9
9
  getCollectionsPath,
10
+ getCollectionTraitFloorsPath,
10
11
  getTopCollectionsPath,
11
12
  getTraitsPath,
12
13
  getTrendingCollectionsPath,
@@ -29,6 +30,7 @@ import {
29
30
  type GetTraitsResponse,
30
31
  type GetTrendingCollectionsArgs,
31
32
  type PaginatedAnalyticsArgs,
33
+ type TraitFloorsResponse,
32
34
  } from "./types"
33
35
 
34
36
  /**
@@ -45,6 +47,20 @@ export class CollectionsAPI {
45
47
  return this.fetcher.get<GetCollectionResponse>(path)
46
48
  }
47
49
 
50
+ /**
51
+ * Fetch floor prices per trait value for a collection.
52
+ *
53
+ * Covers text traits that have at least one active listing, ordered by trait type, then value,
54
+ * then price. Numeric traits are not enumerated here; use {@link getTraits} for their min/max
55
+ * range. Every floor in the response is denominated on the collection's own chain, identified by
56
+ * `chain` plus each entry's `paymentTokenSymbol`.
57
+ */
58
+ async getCollectionTraitFloors(slug: string): Promise<TraitFloorsResponse> {
59
+ return this.fetcher.get<TraitFloorsResponse>(
60
+ getCollectionTraitFloorsPath(slug),
61
+ )
62
+ }
63
+
48
64
  /**
49
65
  * Fetch a list of OpenSea collections.
50
66
  */
package/src/api/types.ts CHANGED
@@ -29,6 +29,8 @@ import type {
29
29
  TokenResponse as ApiTokenResponse,
30
30
  TokenSearchResponse as ApiTokenSearchResponse,
31
31
  Trait as ApiTrait,
32
+ TraitFloorResponse as ApiTraitFloorResponse,
33
+ TraitFloorsResponse as ApiTraitFloorsResponse,
32
34
  TransactionReceiptRequest as ApiTransactionReceiptRequest,
33
35
  TransactionReceiptResponse as ApiTransactionReceiptResponse,
34
36
  ValidateMetadataResponse as ApiValidateMetadataResponse,
@@ -1247,6 +1249,18 @@ export type CreateListingActionsResponse =
1247
1249
  Camelize<ApiCreateListingActionsResponse>
1248
1250
  export type CreateListingFulfillmentActionsResponse =
1249
1251
  Camelize<ApiFulfillmentActionsResponse>
1252
+
1253
+ /**
1254
+ * Floor price for one trait value in one payment currency.
1255
+ * @category API Models
1256
+ */
1257
+ export type TraitFloor = Camelize<ApiTraitFloorResponse>
1258
+
1259
+ /**
1260
+ * Per-trait floor prices for a collection.
1261
+ * @category API Response Types
1262
+ */
1263
+ export type TraitFloorsResponse = Camelize<ApiTraitFloorsResponse>
1250
1264
  export type CreateOfferActionsResponse = Camelize<ApiCreateOfferActionsResponse>
1251
1265
  export type CreateOfferFulfillmentActionsResponse =
1252
1266
  Camelize<ApiFulfillmentActionsResponse>
@@ -5,6 +5,7 @@ import type {
5
5
  operations,
6
6
  } from "@opensea/api-types"
7
7
  import type { Camelize } from "../utils/case"
8
+ import { segment } from "./apiPaths"
8
9
  import type { WalletAuthFetcher } from "./fetcher"
9
10
 
10
11
  type OperationName = keyof operations
@@ -18,8 +19,6 @@ export type WalletAuthQuery<T extends OperationName> = Camelize<
18
19
  OperationQueryParams<T>
19
20
  >
20
21
 
21
- const segment = (value: string | number) => encodeURIComponent(String(value))
22
-
23
22
  /** Typed helpers for wallet-authenticated REST operations. */
24
23
  export class WalletAuthAPI {
25
24
  constructor(private fetcher: WalletAuthFetcher) {}
package/src/types.ts CHANGED
@@ -297,18 +297,27 @@ export type OpenSeaAccount = Camelize<AccountResponse>
297
297
  export type SocialMediaAccount = Camelize<ApiSocialMediaAccount>
298
298
 
299
299
  /**
300
- * Enhanced Error type for rate limit errors that includes retry-after information
300
+ * Error thrown for any non-OK API response. `statusCode` is always set, so a caller can separate
301
+ * a retryable failure from a permanent one without parsing the message. That matters for clients
302
+ * that scrub remote error text before surfacing it, which have no other way to recover the status.
301
303
  * @category API Models
302
304
  */
303
- export interface OpenSeaRateLimitError extends Error {
305
+ export interface OpenSeaApiError extends Error {
304
306
  /** The HTTP status code of the error response */
305
307
  statusCode?: number
306
- /** The number of seconds to wait before retrying the request */
308
+ /** The number of seconds to wait before retrying the request, on rate limit responses */
307
309
  retryAfter?: number
308
310
  /** The response body from the API */
309
311
  responseBody?: unknown
310
312
  }
311
313
 
314
+ /**
315
+ * @deprecated Use {@link OpenSeaApiError}. Retained as an alias: the shape is identical and
316
+ * `retryAfter` was always optional, so existing rate-limit handling is unaffected.
317
+ * @category API Models
318
+ */
319
+ export type OpenSeaRateLimitError = OpenSeaApiError
320
+
312
321
  /**
313
322
  * Options for controlling HTTP request behavior.
314
323
  * @category API Models