@opensea/sdk 10.2.0 → 10.3.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.
package/src/api/types.ts CHANGED
@@ -13,6 +13,36 @@ import type {
13
13
  } from "../orders/types"
14
14
  import type { OpenSeaCollection } from "../types"
15
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
+
16
46
  /**
17
47
  * Response from OpenSea API for building an offer.
18
48
  * @category API Response Types
@@ -645,7 +675,11 @@ export type AssetEvent =
645
675
  | MintEvent
646
676
 
647
677
  /**
648
- * 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
+ *
649
683
  * @category API Query Args
650
684
  */
651
685
  export interface GetEventsArgs {
@@ -663,6 +697,18 @@ export interface GetEventsArgs {
663
697
  chain?: string
664
698
  }
665
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
+
666
712
  /**
667
713
  * Response from OpenSea API for fetching events.
668
714
  * @category API Response Types
@@ -1250,3 +1296,62 @@ export type ValidateMetadataResponse = {
1250
1296
  * @category API Response Types
1251
1297
  */
1252
1298
  export type GetNFTMetadataResponse = AssetMetadataResponse
1299
+
1300
+ // ─── Cross-chain fulfillment types ──────────────────────────────────
1301
+
1302
+ /**
1303
+ * A single listing to fulfill in a cross-chain fulfillment request.
1304
+ * @category API Models
1305
+ */
1306
+ export type CrossChainListing = {
1307
+ /** Order hash (66 chars, starts with 0x) */
1308
+ hash: string
1309
+ /** Chain slug where the listing lives (must be EVM) */
1310
+ chain: string
1311
+ /** Seaport contract address */
1312
+ protocol_address: string
1313
+ }
1314
+
1315
+ /**
1316
+ * Request body for the cross-chain fulfillment endpoint.
1317
+ * @category API Query Args
1318
+ */
1319
+ export type CrossChainFulfillmentDataRequest = {
1320
+ /** Array of listings to fulfill (up to 50) */
1321
+ listings: CrossChainListing[]
1322
+ /** The buyer's wallet */
1323
+ fulfiller: { address: string }
1324
+ /** Payment token details */
1325
+ payment: {
1326
+ /** Chain slug of the payment token (EVM or SVM) */
1327
+ chain: string
1328
+ /** Payment token contract address (0x0...0 for native, Base58 for Solana) */
1329
+ token_address: string
1330
+ }
1331
+ /** Optional: different recipient address for the NFTs */
1332
+ recipient?: string
1333
+ }
1334
+
1335
+ /**
1336
+ * A single transaction returned by the cross-chain fulfillment endpoint.
1337
+ * @category API Response Types
1338
+ */
1339
+ export type CrossChainTransaction = {
1340
+ /** Chain slug for the transaction */
1341
+ chain: string
1342
+ /** Contract address to call */
1343
+ to: string
1344
+ /** Encoded calldata */
1345
+ data: string
1346
+ /** Wei amount as string */
1347
+ value: string
1348
+ }
1349
+
1350
+ /**
1351
+ * Response from the cross-chain fulfillment endpoint.
1352
+ * @category API Response Types
1353
+ */
1354
+ export type CrossChainFulfillmentDataResponse = {
1355
+ /** Ordered list of transactions to sign and submit */
1356
+ transactions: CrossChainTransaction[]
1357
+ }
@@ -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
@@ -19,7 +19,6 @@ import type {
19
19
  AssetWithTokenStandard,
20
20
  Chain,
21
21
  EventData,
22
- OpenSeaAPIConfig,
23
22
  } from "../types"
24
23
  import { EventType, OrderSide } from "../types"
25
24
  import { checksumAddress } from "../utils/address"
@@ -360,6 +359,46 @@ export class BaseOpenSeaSDK {
360
359
  return this._fulfillmentManager.fulfillPrivateOrder(options)
361
360
  }
362
361
 
362
+ /**
363
+ * Get cross-chain fulfillment data for one or more listings.
364
+ * Supports same-chain, cross-token, and cross-chain purchases (up to 50 listings).
365
+ * All listings must be EVM (Seaport orders). Payment can be from any chain (EVM or SVM).
366
+ * Returns an ordered list of transactions to sign and submit.
367
+ * @param options
368
+ * @param options.listings Array of listings to fulfill (order hash, chain, protocol address)
369
+ * @param options.fulfillerAddress The buyer's wallet address
370
+ * @param options.paymentChain Chain slug of the payment token (EVM or SVM)
371
+ * @param options.paymentTokenAddress Payment token contract address (0x0...0 for native)
372
+ * @param options.recipientAddress Optional different recipient for the NFTs
373
+ */
374
+ public async getCrossChainFulfillmentData(options: {
375
+ listings: Array<{
376
+ hash: string
377
+ chain: string
378
+ protocolAddress: string
379
+ }>
380
+ fulfillerAddress: string
381
+ paymentChain: string
382
+ paymentTokenAddress: string
383
+ recipientAddress?: string
384
+ }) {
385
+ return this.api.getCrossChainFulfillmentData({
386
+ listings: options.listings.map(l => ({
387
+ hash: l.hash,
388
+ chain: l.chain,
389
+ protocol_address: l.protocolAddress,
390
+ })),
391
+ fulfiller: { address: options.fulfillerAddress },
392
+ payment: {
393
+ chain: options.paymentChain,
394
+ token_address: options.paymentTokenAddress,
395
+ },
396
+ ...(options.recipientAddress
397
+ ? { recipient: options.recipientAddress }
398
+ : {}),
399
+ })
400
+ }
401
+
363
402
  /** Returns whether an order is fulfillable. */
364
403
  public async isOrderFulfillable(options: {
365
404
  order: OrderV2