@opensea/sdk 10.1.0 → 10.2.1

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.
Files changed (48) hide show
  1. package/README.md +13 -2
  2. package/lib/api/api.d.ts +38 -6
  3. package/lib/api/api.js +60 -9
  4. package/lib/api/api.js.map +1 -1
  5. package/lib/api/apiPaths.d.ts +3 -0
  6. package/lib/api/apiPaths.js +13 -1
  7. package/lib/api/apiPaths.js.map +1 -1
  8. package/lib/api/events.d.ts +4 -3
  9. package/lib/api/events.js +14 -2
  10. package/lib/api/events.js.map +1 -1
  11. package/lib/api/listings.d.ts +4 -7
  12. package/lib/api/listings.js +5 -6
  13. package/lib/api/listings.js.map +1 -1
  14. package/lib/api/nfts.d.ts +4 -3
  15. package/lib/api/nfts.js +5 -6
  16. package/lib/api/nfts.js.map +1 -1
  17. package/lib/api/tokens.d.ts +9 -1
  18. package/lib/api/tokens.js +12 -0
  19. package/lib/api/tokens.js.map +1 -1
  20. package/lib/api/types.d.ts +66 -2
  21. package/lib/api/types.js +10 -0
  22. package/lib/api/types.js.map +1 -1
  23. package/lib/index.d.ts +2 -1
  24. package/lib/index.js +3 -1
  25. package/lib/index.js.map +1 -1
  26. package/lib/provider/seaport-bridge.js +6 -2
  27. package/lib/provider/seaport-bridge.js.map +1 -1
  28. package/lib/provider/viem-adapter.js +9 -0
  29. package/lib/provider/viem-adapter.js.map +1 -1
  30. package/lib/sdk/base.d.ts +16 -2
  31. package/lib/sdk/base.js +17 -0
  32. package/lib/sdk/base.js.map +1 -1
  33. package/lib/viem.d.ts +1 -0
  34. package/lib/viem.js +3 -1
  35. package/lib/viem.js.map +1 -1
  36. package/package.json +4 -4
  37. package/src/api/api.ts +76 -7
  38. package/src/api/apiPaths.ts +12 -0
  39. package/src/api/events.ts +20 -4
  40. package/src/api/listings.ts +10 -6
  41. package/src/api/nfts.ts +13 -12
  42. package/src/api/tokens.ts +21 -0
  43. package/src/api/types.ts +82 -2
  44. package/src/index.ts +4 -0
  45. package/src/provider/seaport-bridge.ts +6 -2
  46. package/src/provider/viem-adapter.ts +18 -3
  47. package/src/sdk/base.ts +27 -3
  48. package/src/viem.ts +1 -0
package/src/api/events.ts CHANGED
@@ -6,7 +6,12 @@ import {
6
6
  getEventsByNFTAPIPath,
7
7
  } from "./apiPaths"
8
8
  import type { Fetcher } from "./fetcher"
9
- import type { GetEventsArgs, GetEventsResponse } from "./types"
9
+ import {
10
+ encodeTraitsParam,
11
+ type GetEventsArgs,
12
+ type GetEventsByCollectionArgs,
13
+ type GetEventsResponse,
14
+ } from "./types"
10
15
 
11
16
  /**
12
17
  * Events-related API operations
@@ -40,15 +45,16 @@ export class EventsAPI {
40
45
  }
41
46
 
42
47
  /**
43
- * Gets a list of events for a specific collection.
48
+ * Gets a list of events for a specific collection. Pass `args.traits` to
49
+ * filter server-side; the SDK JSON-encodes the trait array for the request.
44
50
  */
45
51
  async getEventsByCollection(
46
52
  collectionSlug: string,
47
- args?: GetEventsArgs,
53
+ args?: GetEventsByCollectionArgs,
48
54
  ): Promise<GetEventsResponse> {
49
55
  const response = await this.fetcher.get<GetEventsResponse>(
50
56
  getEventsByCollectionAPIPath(collectionSlug),
51
- args,
57
+ encodeArgs(args),
52
58
  )
53
59
  return response
54
60
  }
@@ -69,3 +75,13 @@ export class EventsAPI {
69
75
  return response
70
76
  }
71
77
  }
78
+
79
+ // Returns `undefined` (not `{}`) when no args were passed so the fetcher
80
+ // receives the same shape as before `traits` existed — preserves the
81
+ // pre-feature query string for callers that don't set any args.
82
+ function encodeArgs(args?: GetEventsByCollectionArgs) {
83
+ if (!args) return args
84
+ const { traits, ...rest } = args
85
+ const encoded = encodeTraitsParam(traits)
86
+ return encoded === undefined ? rest : { ...rest, traits: encoded }
87
+ }
@@ -7,7 +7,12 @@ import {
7
7
  getOrdersAPIPath,
8
8
  } from "./apiPaths"
9
9
  import type { Fetcher } from "./fetcher"
10
- import type { GetBestListingResponse, GetListingsResponse } from "./types"
10
+ import {
11
+ encodeTraitsParam,
12
+ type GetBestListingResponse,
13
+ type GetListingsResponse,
14
+ type TraitFilter,
15
+ } from "./types"
11
16
 
12
17
  /**
13
18
  * Listing-related API operations
@@ -65,17 +70,15 @@ export class ListingsAPI {
65
70
  }
66
71
 
67
72
  /**
68
- * Gets the best listings for a given collection.
69
- * @param collectionSlug The collection slug
70
- * @param limit The number of listings to return
71
- * @param next The cursor for pagination
72
- * @param includePrivateListings Whether to include private listings (default: false)
73
+ * Gets the best listings for a given collection. Pass `traits` to filter
74
+ * server-side by item traits (multiple entries are AND-combined).
73
75
  */
74
76
  async getBestListings(
75
77
  collectionSlug: string,
76
78
  limit?: number,
77
79
  next?: string,
78
80
  includePrivateListings?: boolean,
81
+ traits?: TraitFilter[],
79
82
  ): Promise<GetListingsResponse> {
80
83
  const response = await this.fetcher.get<GetListingsResponse>(
81
84
  getBestListingsAPIPath(collectionSlug),
@@ -85,6 +88,7 @@ export class ListingsAPI {
85
88
  ...(includePrivateListings !== undefined && {
86
89
  include_private_listings: includePrivateListings,
87
90
  }),
91
+ traits: encodeTraitsParam(traits),
88
92
  },
89
93
  )
90
94
  return response
package/src/api/nfts.ts CHANGED
@@ -12,13 +12,15 @@ import {
12
12
  getValidateMetadataPath,
13
13
  } from "./apiPaths"
14
14
  import type { Fetcher } from "./fetcher"
15
- import type {
16
- GetCollectionResponse,
17
- GetContractResponse,
18
- GetNFTMetadataResponse,
19
- GetNFTResponse,
20
- ListNFTsResponse,
21
- ValidateMetadataResponse,
15
+ import {
16
+ encodeTraitsParam,
17
+ type GetCollectionResponse,
18
+ type GetContractResponse,
19
+ type GetNFTMetadataResponse,
20
+ type GetNFTResponse,
21
+ type ListNFTsResponse,
22
+ type TraitFilter,
23
+ type ValidateMetadataResponse,
22
24
  } from "./types"
23
25
 
24
26
  /**
@@ -31,19 +33,18 @@ export class NFTsAPI {
31
33
  ) {}
32
34
 
33
35
  /**
34
- * Fetch multiple NFTs for a collection.
36
+ * Fetch multiple NFTs for a collection. Pass `traits` to filter server-side
37
+ * by item traits (multiple entries are AND-combined).
35
38
  */
36
39
  async getNFTsByCollection(
37
40
  slug: string,
38
41
  limit: number | undefined = undefined,
39
42
  next: string | undefined = undefined,
43
+ traits: TraitFilter[] | undefined = undefined,
40
44
  ): Promise<ListNFTsResponse> {
41
45
  const response = await this.fetcher.get<ListNFTsResponse>(
42
46
  getListNFTsByCollectionPath(slug),
43
- {
44
- limit,
45
- next,
46
- },
47
+ { limit, next, traits: encodeTraitsParam(traits) },
47
48
  )
48
49
  return response
49
50
  }
package/src/api/tokens.ts CHANGED
@@ -1,5 +1,7 @@
1
1
  import {
2
2
  getSwapQuotePath,
3
+ getTokenGroupPath,
4
+ getTokenGroupsPath,
3
5
  getTokenPath,
4
6
  getTopTokensPath,
5
7
  getTrendingTokensPath,
@@ -8,6 +10,9 @@ import type { Fetcher } from "./fetcher"
8
10
  import type {
9
11
  GetSwapQuoteArgs,
10
12
  GetSwapQuoteResponse,
13
+ GetTokenGroupResponse,
14
+ GetTokenGroupsArgs,
15
+ GetTokenGroupsResponse,
11
16
  GetTokenResponse,
12
17
  GetTokensArgs,
13
18
  GetTopTokensResponse,
@@ -64,4 +69,20 @@ export class TokensAPI {
64
69
  )
65
70
  return response
66
71
  }
72
+
73
+ /**
74
+ * Gets a paginated list of token groups (equivalent currencies across chains).
75
+ */
76
+ async getTokenGroups(
77
+ args?: GetTokenGroupsArgs,
78
+ ): Promise<GetTokenGroupsResponse> {
79
+ return this.fetcher.get<GetTokenGroupsResponse>(getTokenGroupsPath(), args)
80
+ }
81
+
82
+ /**
83
+ * Gets a single token group by its slug.
84
+ */
85
+ async getTokenGroup(slug: string): Promise<GetTokenGroupResponse> {
86
+ return this.fetcher.get<GetTokenGroupResponse>(getTokenGroupPath(slug))
87
+ }
67
88
  }
package/src/api/types.ts CHANGED
@@ -1,4 +1,9 @@
1
- import type { AssetMetadataResponse } from "@opensea/api-types"
1
+ import type {
2
+ AssetMetadataResponse,
3
+ InstantApiKeyResponse,
4
+ TokenGroupPaginatedResponse,
5
+ TokenGroupResponse,
6
+ } from "@opensea/api-types"
2
7
  import type { ConsiderationItem } from "@opensea/seaport-js/lib/types"
3
8
  import type {
4
9
  OrderType,
@@ -8,6 +13,36 @@ import type {
8
13
  } from "../orders/types"
9
14
  import type { OpenSeaCollection } from "../types"
10
15
 
16
+ /**
17
+ * A single trait filter used by collection-scoped read endpoints (NFTs by
18
+ * collection, best listings by collection, events by collection). Multiple
19
+ * filters in the same query are AND-combined: returned items must match every
20
+ * specified trait.
21
+ *
22
+ * Distinct from {@link TraitCriteria} (`{type, value}`) which is the offer-
23
+ * creation shape — the wire format differs across endpoints.
24
+ *
25
+ * @category API Query Args
26
+ */
27
+ export interface TraitFilter {
28
+ /** The trait name (e.g. "Background"). */
29
+ traitType: string
30
+ /** The trait value to match (e.g. "Red"). */
31
+ value: string
32
+ }
33
+
34
+ /**
35
+ * Encode a {@link TraitFilter} array as the JSON-string form the API expects
36
+ * on the `traits` query parameter, or `undefined` if the array is empty.
37
+ * Callers spread the result into a query object; query encoders skip
38
+ * undefined keys.
39
+ */
40
+ export function encodeTraitsParam(
41
+ traits: TraitFilter[] | undefined,
42
+ ): string | undefined {
43
+ return traits && traits.length > 0 ? JSON.stringify(traits) : undefined
44
+ }
45
+
11
46
  /**
12
47
  * Response from OpenSea API for building an offer.
13
48
  * @category API Response Types
@@ -640,7 +675,11 @@ export type AssetEvent =
640
675
  | MintEvent
641
676
 
642
677
  /**
643
- * Query args for Get Events endpoints.
678
+ * Query args for the generic event endpoints (`getEvents`,
679
+ * `getEventsByAccount`, `getEventsByNFT`). For the collection-scoped endpoint
680
+ * see {@link GetEventsByCollectionArgs}, which adds server-side trait
681
+ * filtering on top of these fields.
682
+ *
644
683
  * @category API Query Args
645
684
  */
646
685
  export interface GetEventsArgs {
@@ -658,6 +697,18 @@ export interface GetEventsArgs {
658
697
  chain?: string
659
698
  }
660
699
 
700
+ /**
701
+ * Query args for {@link EventsAPI.getEventsByCollection}. Adds server-side
702
+ * trait filtering on top of {@link GetEventsArgs}; multiple traits are
703
+ * AND-combined.
704
+ *
705
+ * @category API Query Args
706
+ */
707
+ export interface GetEventsByCollectionArgs extends GetEventsArgs {
708
+ /** Trait filters; see {@link TraitFilter}. */
709
+ traits?: TraitFilter[]
710
+ }
711
+
661
712
  /**
662
713
  * Response from OpenSea API for fetching events.
663
714
  * @category API Response Types
@@ -802,6 +853,35 @@ export type GetSwapQuoteResponse = {
802
853
  */
803
854
  export type GetTokenResponse = Token
804
855
 
856
+ /**
857
+ * Response from OpenSea API for fetching a token group by slug.
858
+ * @category API Response Types
859
+ */
860
+ export type GetTokenGroupResponse = TokenGroupResponse
861
+
862
+ /**
863
+ * Response from OpenSea API for fetching a paginated list of token groups.
864
+ * @category API Response Types
865
+ */
866
+ export type GetTokenGroupsResponse = TokenGroupPaginatedResponse
867
+
868
+ /**
869
+ * Query args for the Get Token Groups endpoint.
870
+ * @category API Query Args
871
+ */
872
+ export interface GetTokenGroupsArgs {
873
+ /** Number of results to return (default: 50, max: 100) */
874
+ limit?: number
875
+ /** Cursor for pagination */
876
+ cursor?: string
877
+ }
878
+
879
+ /**
880
+ * Response from OpenSea API for requesting an instant API key.
881
+ * @category API Response Types
882
+ */
883
+ export type RequestInstantApiKeyResponse = InstantApiKeyResponse
884
+
805
885
  /**
806
886
  * Query args for the Search endpoint.
807
887
  * @category API Query Args
package/src/index.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { OpenSeaAPI } from "./api/api"
1
2
  import { OpenSeaSDK } from "./sdk"
2
3
 
3
4
  export * from "./api/types"
@@ -25,6 +26,9 @@ export * from "./utils"
25
26
  * ```
26
27
  */
27
28
  export {
29
+ // API client (for direct use or accessing static helpers like
30
+ // `OpenSeaAPI.requestInstantApiKey()`)
31
+ OpenSeaAPI,
28
32
  // Main SDK export
29
33
  OpenSeaSDK,
30
34
  }
@@ -115,12 +115,16 @@ class ViemEthersSigner extends AbstractSigner {
115
115
  })
116
116
 
117
117
  // Return an ethers-compatible TransactionResponse by fetching from the provider
118
- const response = await this.provider!.getTransaction(hash)
118
+ const provider = this.provider
119
+ if (!provider) {
120
+ throw new Error("Provider is required to fetch transaction response")
121
+ }
122
+ const response = await provider.getTransaction(hash)
119
123
  if (!response) {
120
124
  // Fallback: construct minimal response if the tx isn't indexed yet
121
125
  return {
122
126
  hash,
123
- wait: () => this.provider!.waitForTransaction(hash),
127
+ wait: () => provider.waitForTransaction(hash),
124
128
  } as unknown as TransactionResponse
125
129
  }
126
130
  return response
@@ -60,11 +60,16 @@ function createViemSigner(
60
60
  },
61
61
 
62
62
  async sendTransaction(tx) {
63
+ if (!walletClient.account) {
64
+ throw new Error(
65
+ "WalletClient must have an account. Use `createWalletClient` with an `account` parameter.",
66
+ )
67
+ }
63
68
  const hash = await walletClient.sendTransaction({
64
69
  to: tx.to as `0x${string}`,
65
70
  data: tx.data as `0x${string}` | undefined,
66
71
  value: tx.value,
67
- account: walletClient.account!,
72
+ account: walletClient.account,
68
73
  chain: walletClient.chain,
69
74
  ...(tx.overrides as any),
70
75
  })
@@ -77,6 +82,11 @@ function createViemSigner(
77
82
  },
78
83
 
79
84
  async signTypedData(domain, types, value) {
85
+ if (!walletClient.account) {
86
+ throw new Error(
87
+ "WalletClient must have an account. Use `createWalletClient` with an `account` parameter.",
88
+ )
89
+ }
80
90
  return walletClient.signTypedData({
81
91
  domain: {
82
92
  chainId: Number(domain.chainId),
@@ -89,7 +99,7 @@ function createViemSigner(
89
99
  Object.keys(types).find(key => key !== "EIP712Domain") ||
90
100
  Object.keys(types)[0],
91
101
  message: value,
92
- account: walletClient.account!,
102
+ account: walletClient.account,
93
103
  })
94
104
  },
95
105
  }
@@ -134,13 +144,18 @@ export function createViemContractCaller(
134
144
  if (!walletClient) {
135
145
  throw new Error("A WalletClient is required for write operations")
136
146
  }
147
+ if (!walletClient.account) {
148
+ throw new Error(
149
+ "WalletClient must have an account. Use `createWalletClient` with an `account` parameter.",
150
+ )
151
+ }
137
152
  const hash = await walletClient.writeContract({
138
153
  address: address as `0x${string}`,
139
154
  abi: abi as any,
140
155
  functionName,
141
156
  args: args as any,
142
157
  value,
143
- account: walletClient.account!,
158
+ account: walletClient.account,
144
159
  chain: walletClient.chain,
145
160
  ...(overrides as any),
146
161
  })
package/src/sdk/base.ts CHANGED
@@ -2,8 +2,14 @@ import EventEmitter = require("node:events")
2
2
 
3
3
  import type { Seaport } from "@opensea/seaport-js"
4
4
  import type { OrderComponents } from "@opensea/seaport-js/lib/types"
5
- import type { OpenSeaAPI } from "../api/api"
6
- import type { CollectionOffer, Listing, Offer, Order } from "../api/types"
5
+ import { OpenSeaAPI } from "../api/api"
6
+ import type {
7
+ CollectionOffer,
8
+ Listing,
9
+ Offer,
10
+ Order,
11
+ RequestInstantApiKeyResponse,
12
+ } from "../api/types"
7
13
  import { ZERO_ADDRESS } from "../constants"
8
14
  import type { OrderV2 } from "../orders/types"
9
15
  import type { ContractCaller, OpenSeaWallet } from "../provider/types"
@@ -13,7 +19,6 @@ import type {
13
19
  AssetWithTokenStandard,
14
20
  Chain,
15
21
  EventData,
16
- OpenSeaAPIConfig,
17
22
  } from "../types"
18
23
  import { EventType, OrderSide } from "../types"
19
24
  import { checksumAddress } from "../utils/address"
@@ -103,6 +108,25 @@ export class BaseOpenSeaSDK {
103
108
  )
104
109
  }
105
110
 
111
+ /**
112
+ * Request a free-tier OpenSea API key without authentication. The returned
113
+ * key can be passed as `apiKey` into the SDK constructor to bootstrap usage.
114
+ * Rate limited to 3 keys per hour per IP; keys expire after 30 days.
115
+ *
116
+ * @example
117
+ * ```ts
118
+ * const { api_key } = await OpenSeaSDK.requestInstantApiKey()
119
+ * const sdk = new OpenSeaSDK(provider, { apiKey: api_key })
120
+ * ```
121
+ *
122
+ * @param apiBaseUrl Optional base URL override (defaults to mainnet).
123
+ */
124
+ public static async requestInstantApiKey(
125
+ apiBaseUrl?: string,
126
+ ): Promise<RequestInstantApiKeyResponse> {
127
+ return OpenSeaAPI.requestInstantApiKey(apiBaseUrl)
128
+ }
129
+
106
130
  // ─── Event Listeners ───────────────────────────────────────────────
107
131
 
108
132
  /**
package/src/viem.ts CHANGED
@@ -38,6 +38,7 @@ import {
38
38
  } from "./utils/utils"
39
39
 
40
40
  // Re-export everything from the main entry point
41
+ export { OpenSeaAPI } from "./api/api"
41
42
  export * from "./api/types"
42
43
  export * from "./constants"
43
44
  export * from "./orders/types"