@opensea/sdk 9.0.0 → 10.1.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.
Files changed (311) hide show
  1. package/README.md +35 -6
  2. package/lib/abi/abis.d.ts +301 -0
  3. package/lib/abi/abis.js +231 -0
  4. package/lib/abi/abis.js.map +1 -0
  5. package/lib/api/api.d.ts +26 -2
  6. package/lib/api/api.js +83 -51
  7. package/lib/api/api.js.map +1 -1
  8. package/lib/api/apiPaths.d.ts +2 -0
  9. package/lib/api/apiPaths.js +9 -1
  10. package/lib/api/apiPaths.js.map +1 -1
  11. package/lib/api/nfts.d.ts +13 -2
  12. package/lib/api/nfts.js +18 -0
  13. package/lib/api/nfts.js.map +1 -1
  14. package/lib/api/orders.js +2 -2
  15. package/lib/api/orders.js.map +1 -1
  16. package/lib/api/types.d.ts +7 -0
  17. package/lib/api/types.js.map +1 -1
  18. package/lib/constants.d.ts +2 -2
  19. package/lib/constants.js +7 -4
  20. package/lib/constants.js.map +1 -1
  21. package/lib/index.d.ts +2 -0
  22. package/lib/index.js +1 -0
  23. package/lib/index.js.map +1 -1
  24. package/lib/orders/privateListings.js +2 -2
  25. package/lib/orders/privateListings.js.map +1 -1
  26. package/lib/orders/utils.js +9 -1
  27. package/lib/orders/utils.js.map +1 -1
  28. package/lib/provider/ethers-adapter.d.ts +17 -0
  29. package/lib/provider/ethers-adapter.js +135 -0
  30. package/lib/provider/ethers-adapter.js.map +1 -0
  31. package/lib/provider/seaport-bridge.d.ts +11 -0
  32. package/lib/provider/seaport-bridge.js +130 -0
  33. package/lib/provider/seaport-bridge.js.map +1 -0
  34. package/lib/provider/types.d.ts +62 -0
  35. package/lib/provider/types.js +7 -0
  36. package/lib/provider/types.js.map +1 -0
  37. package/lib/provider/viem-adapter.d.ts +27 -0
  38. package/lib/provider/viem-adapter.js +122 -0
  39. package/lib/provider/viem-adapter.js.map +1 -0
  40. package/lib/sdk/assets.d.ts +7 -23
  41. package/lib/sdk/assets.js +101 -77
  42. package/lib/sdk/assets.js.map +1 -1
  43. package/lib/sdk/base.d.ts +350 -0
  44. package/lib/sdk/base.js +325 -0
  45. package/lib/sdk/base.js.map +1 -0
  46. package/lib/sdk/cancellation.d.ts +1 -2
  47. package/lib/sdk/cancellation.js +4 -4
  48. package/lib/sdk/cancellation.js.map +1 -1
  49. package/lib/sdk/context.d.ts +5 -5
  50. package/lib/sdk/fulfillment.d.ts +20 -59
  51. package/lib/sdk/fulfillment.js +18 -58
  52. package/lib/sdk/fulfillment.js.map +1 -1
  53. package/lib/sdk/orders.d.ts +25 -26
  54. package/lib/sdk/orders.js +8 -9
  55. package/lib/sdk/orders.js.map +1 -1
  56. package/lib/sdk/tokens.d.ts +3 -3
  57. package/lib/sdk/tokens.js +17 -7
  58. package/lib/sdk/tokens.js.map +1 -1
  59. package/lib/sdk.d.ts +16 -550
  60. package/lib/sdk.js +35 -663
  61. package/lib/sdk.js.map +1 -1
  62. package/lib/types.d.ts +11 -6
  63. package/lib/types.js +3 -3
  64. package/lib/types.js.map +1 -1
  65. package/lib/utils/address.d.ts +12 -0
  66. package/lib/utils/address.js +39 -0
  67. package/lib/utils/address.js.map +1 -0
  68. package/lib/utils/chain.d.ts +1 -1
  69. package/lib/utils/fees.d.ts +5 -0
  70. package/lib/utils/fees.js +24 -6
  71. package/lib/utils/fees.js.map +1 -1
  72. package/lib/utils/protocol.js +5 -5
  73. package/lib/utils/protocol.js.map +1 -1
  74. package/lib/utils/units.d.ts +12 -0
  75. package/lib/utils/units.js +43 -0
  76. package/lib/utils/units.js.map +1 -0
  77. package/lib/utils/utils.d.ts +2 -10
  78. package/lib/utils/utils.js +2 -17
  79. package/lib/utils/utils.js.map +1 -1
  80. package/lib/viem.d.ts +44 -0
  81. package/lib/viem.js +114 -0
  82. package/lib/viem.js.map +1 -0
  83. package/package.json +31 -13
  84. package/src/abi/abis.ts +236 -0
  85. package/src/api/api.ts +100 -59
  86. package/src/api/apiPaths.ts +16 -0
  87. package/src/api/nfts.ts +37 -1
  88. package/src/api/orders.ts +2 -2
  89. package/src/api/types.ts +8 -0
  90. package/src/constants.ts +7 -3
  91. package/src/index.ts +8 -0
  92. package/src/orders/privateListings.ts +2 -2
  93. package/src/orders/utils.ts +8 -1
  94. package/src/provider/ethers-adapter.ts +182 -0
  95. package/src/provider/seaport-bridge.ts +163 -0
  96. package/src/provider/types.ts +67 -0
  97. package/src/provider/viem-adapter.ts +165 -0
  98. package/src/sdk/assets.ts +128 -158
  99. package/src/sdk/base.ts +577 -0
  100. package/src/sdk/cancellation.ts +6 -9
  101. package/src/sdk/context.ts +5 -5
  102. package/src/sdk/fulfillment.ts +34 -73
  103. package/src/sdk/orders.ts +44 -44
  104. package/src/sdk/tokens.ts +18 -18
  105. package/src/sdk.ts +40 -1011
  106. package/src/types.ts +12 -6
  107. package/src/utils/address.ts +40 -0
  108. package/src/utils/fees.ts +28 -8
  109. package/src/utils/protocol.ts +5 -5
  110. package/src/utils/units.ts +47 -0
  111. package/src/utils/utils.ts +2 -22
  112. package/src/viem.ts +125 -0
  113. package/lib/src/api/accounts.d.ts +0 -18
  114. package/lib/src/api/accounts.js +0 -30
  115. package/lib/src/api/accounts.js.map +0 -1
  116. package/lib/src/api/api.d.ts +0 -429
  117. package/lib/src/api/api.js +0 -652
  118. package/lib/src/api/api.js.map +0 -1
  119. package/lib/src/api/apiPaths.d.ts +0 -37
  120. package/lib/src/api/apiPaths.js +0 -140
  121. package/lib/src/api/apiPaths.js.map +0 -1
  122. package/lib/src/api/collections.d.ts +0 -26
  123. package/lib/src/api/collections.js +0 -57
  124. package/lib/src/api/collections.js.map +0 -1
  125. package/lib/src/api/events.d.ts +0 -26
  126. package/lib/src/api/events.js +0 -42
  127. package/lib/src/api/events.js.map +0 -1
  128. package/lib/src/api/fetcher.d.ts +0 -24
  129. package/lib/src/api/fetcher.js +0 -3
  130. package/lib/src/api/fetcher.js.map +0 -1
  131. package/lib/src/api/index.d.ts +0 -2
  132. package/lib/src/api/index.js +0 -19
  133. package/lib/src/api/index.js.map +0 -1
  134. package/lib/src/api/listings.d.ts +0 -44
  135. package/lib/src/api/listings.js +0 -86
  136. package/lib/src/api/listings.js.map +0 -1
  137. package/lib/src/api/nfts.d.ts +0 -35
  138. package/lib/src/api/nfts.js +0 -66
  139. package/lib/src/api/nfts.js.map +0 -1
  140. package/lib/src/api/offers.d.ts +0 -54
  141. package/lib/src/api/offers.js +0 -122
  142. package/lib/src/api/offers.js.map +0 -1
  143. package/lib/src/api/orders.d.ts +0 -50
  144. package/lib/src/api/orders.js +0 -151
  145. package/lib/src/api/orders.js.map +0 -1
  146. package/lib/src/api/search.d.ts +0 -13
  147. package/lib/src/api/search.js +0 -21
  148. package/lib/src/api/search.js.map +0 -1
  149. package/lib/src/api/tokens.d.ts +0 -25
  150. package/lib/src/api/tokens.js +0 -42
  151. package/lib/src/api/tokens.js.map +0 -1
  152. package/lib/src/api/types.d.ts +0 -840
  153. package/lib/src/api/types.js +0 -65
  154. package/lib/src/api/types.js.map +0 -1
  155. package/lib/src/constants.d.ts +0 -22
  156. package/lib/src/constants.js +0 -52
  157. package/lib/src/constants.js.map +0 -1
  158. package/lib/src/index.d.ts +0 -18
  159. package/lib/src/index.js +0 -24
  160. package/lib/src/index.js.map +0 -1
  161. package/lib/src/orders/privateListings.d.ts +0 -12
  162. package/lib/src/orders/privateListings.js +0 -130
  163. package/lib/src/orders/privateListings.js.map +0 -1
  164. package/lib/src/orders/types.d.ts +0 -160
  165. package/lib/src/orders/types.js +0 -10
  166. package/lib/src/orders/types.js.map +0 -1
  167. package/lib/src/orders/utils.d.ts +0 -89
  168. package/lib/src/orders/utils.js +0 -177
  169. package/lib/src/orders/utils.js.map +0 -1
  170. package/lib/src/sdk/assets.d.ts +0 -104
  171. package/lib/src/sdk/assets.js +0 -397
  172. package/lib/src/sdk/assets.js.map +0 -1
  173. package/lib/src/sdk/cancellation.d.ts +0 -97
  174. package/lib/src/sdk/cancellation.js +0 -234
  175. package/lib/src/sdk/cancellation.js.map +0 -1
  176. package/lib/src/sdk/context.d.ts +0 -28
  177. package/lib/src/sdk/context.js +0 -3
  178. package/lib/src/sdk/context.js.map +0 -1
  179. package/lib/src/sdk/fulfillment.d.ts +0 -153
  180. package/lib/src/sdk/fulfillment.js +0 -296
  181. package/lib/src/sdk/fulfillment.js.map +0 -1
  182. package/lib/src/sdk/orders.d.ts +0 -253
  183. package/lib/src/sdk/orders.js +0 -677
  184. package/lib/src/sdk/orders.js.map +0 -1
  185. package/lib/src/sdk/tokens.d.ts +0 -31
  186. package/lib/src/sdk/tokens.js +0 -64
  187. package/lib/src/sdk/tokens.js.map +0 -1
  188. package/lib/src/sdk.d.ts +0 -560
  189. package/lib/src/sdk.js +0 -675
  190. package/lib/src/sdk.js.map +0 -1
  191. package/lib/src/typechain/contracts/ERC1155.d.ts +0 -236
  192. package/lib/src/typechain/contracts/ERC1155.js +0 -3
  193. package/lib/src/typechain/contracts/ERC1155.js.map +0 -1
  194. package/lib/src/typechain/contracts/ERC20.d.ts +0 -141
  195. package/lib/src/typechain/contracts/ERC20.js +0 -3
  196. package/lib/src/typechain/contracts/ERC20.js.map +0 -1
  197. package/lib/src/typechain/contracts/ERC721.d.ts +0 -213
  198. package/lib/src/typechain/contracts/ERC721.js +0 -3
  199. package/lib/src/typechain/contracts/ERC721.js.map +0 -1
  200. package/lib/src/typechain/contracts/Multicall3.d.ts +0 -57
  201. package/lib/src/typechain/contracts/Multicall3.js +0 -3
  202. package/lib/src/typechain/contracts/Multicall3.js.map +0 -1
  203. package/lib/src/typechain/contracts/TransferHelper.d.ts +0 -55
  204. package/lib/src/typechain/contracts/TransferHelper.js +0 -3
  205. package/lib/src/typechain/contracts/TransferHelper.js.map +0 -1
  206. package/lib/src/typechain/contracts/common.d.ts +0 -50
  207. package/lib/src/typechain/contracts/common.js +0 -3
  208. package/lib/src/typechain/contracts/common.js.map +0 -1
  209. package/lib/src/typechain/contracts/factories/ERC1155__factory.d.ts +0 -250
  210. package/lib/src/typechain/contracts/factories/ERC1155__factory.js +0 -332
  211. package/lib/src/typechain/contracts/factories/ERC1155__factory.js.map +0 -1
  212. package/lib/src/typechain/contracts/factories/ERC20__factory.d.ts +0 -174
  213. package/lib/src/typechain/contracts/factories/ERC20__factory.js +0 -240
  214. package/lib/src/typechain/contracts/factories/ERC20__factory.js.map +0 -1
  215. package/lib/src/typechain/contracts/factories/ERC721__factory.d.ts +0 -268
  216. package/lib/src/typechain/contracts/factories/ERC721__factory.js +0 -351
  217. package/lib/src/typechain/contracts/factories/ERC721__factory.js.map +0 -1
  218. package/lib/src/typechain/contracts/factories/Multicall3__factory.d.ts +0 -43
  219. package/lib/src/typechain/contracts/factories/Multicall3__factory.js +0 -68
  220. package/lib/src/typechain/contracts/factories/Multicall3__factory.js.map +0 -1
  221. package/lib/src/typechain/contracts/factories/TransferHelper__factory.d.ts +0 -46
  222. package/lib/src/typechain/contracts/factories/TransferHelper__factory.js +0 -71
  223. package/lib/src/typechain/contracts/factories/TransferHelper__factory.js.map +0 -1
  224. package/lib/src/typechain/contracts/factories/index.d.ts +0 -5
  225. package/lib/src/typechain/contracts/factories/index.js +0 -17
  226. package/lib/src/typechain/contracts/factories/index.js.map +0 -1
  227. package/lib/src/typechain/contracts/index.d.ts +0 -11
  228. package/lib/src/typechain/contracts/index.js +0 -48
  229. package/lib/src/typechain/contracts/index.js.map +0 -1
  230. package/lib/src/types.d.ts +0 -387
  231. package/lib/src/types.js +0 -127
  232. package/lib/src/types.js.map +0 -1
  233. package/lib/src/utils/chain.d.ts +0 -60
  234. package/lib/src/utils/chain.js +0 -248
  235. package/lib/src/utils/chain.js.map +0 -1
  236. package/lib/src/utils/converters.d.ts +0 -37
  237. package/lib/src/utils/converters.js +0 -137
  238. package/lib/src/utils/converters.js.map +0 -1
  239. package/lib/src/utils/dateHelper.d.ts +0 -38
  240. package/lib/src/utils/dateHelper.js +0 -52
  241. package/lib/src/utils/dateHelper.js.map +0 -1
  242. package/lib/src/utils/fees.d.ts +0 -13
  243. package/lib/src/utils/fees.js +0 -29
  244. package/lib/src/utils/fees.js.map +0 -1
  245. package/lib/src/utils/index.d.ts +0 -2
  246. package/lib/src/utils/index.js +0 -19
  247. package/lib/src/utils/index.js.map +0 -1
  248. package/lib/src/utils/protocol.d.ts +0 -75
  249. package/lib/src/utils/protocol.js +0 -161
  250. package/lib/src/utils/protocol.js.map +0 -1
  251. package/lib/src/utils/rateLimit.d.ts +0 -34
  252. package/lib/src/utils/rateLimit.js +0 -97
  253. package/lib/src/utils/rateLimit.js.map +0 -1
  254. package/lib/src/utils/stringHelper.d.ts +0 -18
  255. package/lib/src/utils/stringHelper.js +0 -24
  256. package/lib/src/utils/stringHelper.js.map +0 -1
  257. package/lib/src/utils/utils.d.ts +0 -18
  258. package/lib/src/utils/utils.js +0 -45
  259. package/lib/src/utils/utils.js.map +0 -1
  260. package/lib/typechain/contracts/ERC1155.d.ts +0 -236
  261. package/lib/typechain/contracts/ERC1155.js +0 -3
  262. package/lib/typechain/contracts/ERC1155.js.map +0 -1
  263. package/lib/typechain/contracts/ERC20.d.ts +0 -141
  264. package/lib/typechain/contracts/ERC20.js +0 -3
  265. package/lib/typechain/contracts/ERC20.js.map +0 -1
  266. package/lib/typechain/contracts/ERC721.d.ts +0 -213
  267. package/lib/typechain/contracts/ERC721.js +0 -3
  268. package/lib/typechain/contracts/ERC721.js.map +0 -1
  269. package/lib/typechain/contracts/Multicall3.d.ts +0 -57
  270. package/lib/typechain/contracts/Multicall3.js +0 -3
  271. package/lib/typechain/contracts/Multicall3.js.map +0 -1
  272. package/lib/typechain/contracts/TransferHelper.d.ts +0 -55
  273. package/lib/typechain/contracts/TransferHelper.js +0 -3
  274. package/lib/typechain/contracts/TransferHelper.js.map +0 -1
  275. package/lib/typechain/contracts/common.d.ts +0 -50
  276. package/lib/typechain/contracts/common.js +0 -3
  277. package/lib/typechain/contracts/common.js.map +0 -1
  278. package/lib/typechain/contracts/factories/ERC1155__factory.d.ts +0 -250
  279. package/lib/typechain/contracts/factories/ERC1155__factory.js +0 -332
  280. package/lib/typechain/contracts/factories/ERC1155__factory.js.map +0 -1
  281. package/lib/typechain/contracts/factories/ERC20__factory.d.ts +0 -174
  282. package/lib/typechain/contracts/factories/ERC20__factory.js +0 -240
  283. package/lib/typechain/contracts/factories/ERC20__factory.js.map +0 -1
  284. package/lib/typechain/contracts/factories/ERC721__factory.d.ts +0 -268
  285. package/lib/typechain/contracts/factories/ERC721__factory.js +0 -351
  286. package/lib/typechain/contracts/factories/ERC721__factory.js.map +0 -1
  287. package/lib/typechain/contracts/factories/Multicall3__factory.d.ts +0 -43
  288. package/lib/typechain/contracts/factories/Multicall3__factory.js +0 -68
  289. package/lib/typechain/contracts/factories/Multicall3__factory.js.map +0 -1
  290. package/lib/typechain/contracts/factories/TransferHelper__factory.d.ts +0 -46
  291. package/lib/typechain/contracts/factories/TransferHelper__factory.js +0 -71
  292. package/lib/typechain/contracts/factories/TransferHelper__factory.js.map +0 -1
  293. package/lib/typechain/contracts/factories/index.d.ts +0 -5
  294. package/lib/typechain/contracts/factories/index.js +0 -17
  295. package/lib/typechain/contracts/factories/index.js.map +0 -1
  296. package/lib/typechain/contracts/index.d.ts +0 -11
  297. package/lib/typechain/contracts/index.js +0 -48
  298. package/lib/typechain/contracts/index.js.map +0 -1
  299. package/src/typechain/contracts/ERC1155.ts +0 -440
  300. package/src/typechain/contracts/ERC20.ts +0 -286
  301. package/src/typechain/contracts/ERC721.ts +0 -412
  302. package/src/typechain/contracts/Multicall3.ts +0 -117
  303. package/src/typechain/contracts/TransferHelper.ts +0 -122
  304. package/src/typechain/contracts/common.ts +0 -131
  305. package/src/typechain/contracts/factories/ERC1155__factory.ts +0 -331
  306. package/src/typechain/contracts/factories/ERC20__factory.ts +0 -239
  307. package/src/typechain/contracts/factories/ERC721__factory.ts +0 -350
  308. package/src/typechain/contracts/factories/Multicall3__factory.ts +0 -67
  309. package/src/typechain/contracts/factories/TransferHelper__factory.ts +0 -76
  310. package/src/typechain/contracts/factories/index.ts +0 -8
  311. package/src/typechain/contracts/index.ts +0 -14
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@opensea/sdk",
3
- "version": "9.0.0",
4
- "description": "TypeScript SDK for the OpenSea marketplace helps developers build new experiences using NFTs and our marketplace data",
3
+ "version": "10.1.0",
4
+ "description": "TypeScript SDK for the OpenSea marketplace helps developers build new experiences using NFTs, tokens, and our marketplace data",
5
5
  "license": "MIT",
6
6
  "author": "OpenSea Developers",
7
7
  "homepage": "https://docs.opensea.io/reference/api-overview",
@@ -14,20 +14,29 @@
14
14
  },
15
15
  "type": "commonjs",
16
16
  "main": "lib/index.js",
17
+ "exports": {
18
+ ".": {
19
+ "types": "./lib/index.d.ts",
20
+ "default": "./lib/index.js"
21
+ },
22
+ "./viem": {
23
+ "types": "./lib/viem.d.ts",
24
+ "default": "./lib/viem.js"
25
+ }
26
+ },
17
27
  "files": [
18
28
  "lib",
19
29
  "src"
20
30
  ],
21
31
  "scripts": {
22
- "abi-type-gen": "typechain --target=ethers-v6 src/abi/*.json --out-dir=src/typechain/contracts",
23
- "build": "npm run abi-type-gen && tsc -p tsconfig.build.json",
24
- "check-types": "tsc --noEmit --project tsconfig.json",
32
+ "build": "tsc",
33
+ "check-types": "tsc -p tsconfig.check.json",
25
34
  "docs-build": "typedoc",
26
35
  "docs-build-md": "typedoc --plugin typedoc-plugin-markdown",
27
- "format": "biome format --config-path ../.. --write .",
28
- "format:check": "biome format --config-path ../.. .",
29
- "lint": "concurrently \"npm run check-types\" \"biome check --config-path ../.. .\"",
30
- "lint:fix": "biome check --config-path ../.. --write .",
36
+ "format": "biome format --config-path . --write .",
37
+ "format:check": "biome format --config-path . .",
38
+ "lint": "biome check --config-path . .",
39
+ "lint:fix": "biome check --config-path . --write .",
31
40
  "test": "vitest run",
32
41
  "test:all": "concurrently \"npm run test\" \"npm run test:integration\"",
33
42
  "test:coverage": "vitest run --coverage",
@@ -35,22 +44,31 @@
35
44
  },
36
45
  "types": "lib/index.d.ts",
37
46
  "dependencies": {
38
- "@opensea/api-types": "workspace:^",
47
+ "@noble/hashes": "^2.0.1",
48
+ "@opensea/api-types": "^0.2.0",
39
49
  "@opensea/seaport-js": "^4.0.7",
40
50
  "ethers": "^6.16.0"
41
51
  },
52
+ "peerDependencies": {
53
+ "viem": "^2.0.0"
54
+ },
55
+ "peerDependenciesMeta": {
56
+ "viem": {
57
+ "optional": true
58
+ }
59
+ },
42
60
  "devDependencies": {
43
- "@typechain/ethers-v6": "^0.5.1",
44
61
  "@types/node": "^25.4.0",
62
+ "viem": "2.23.2",
45
63
  "@vitest/coverage-v8": "^3.2.4",
46
64
  "concurrently": "^9.2.1",
47
65
  "dotenv": "^17.3.1",
48
- "typechain": "^8.0.0",
49
66
  "typedoc": "^0.28.17",
50
67
  "typedoc-plugin-markdown": "^4.10.0",
51
68
  "typescript": "^6.0.2",
52
69
  "typescript-eslint": "^8.57.0",
53
- "vitest": "^3.2.4"
70
+ "vitest": "^3.2.4",
71
+ "@biomejs/biome": "^2.4.10"
54
72
  },
55
73
  "keywords": [
56
74
  "collectibles",
@@ -0,0 +1,236 @@
1
+ /**
2
+ * Minimal ABI definitions for the contract calls the SDK makes.
3
+ * These replace the TypeChain-generated factories from v9.
4
+ */
5
+
6
+ export const ERC20_ABI = [
7
+ {
8
+ name: "balanceOf",
9
+ type: "function",
10
+ stateMutability: "view",
11
+ inputs: [{ name: "account", type: "address" }],
12
+ outputs: [{ name: "", type: "uint256" }],
13
+ },
14
+ {
15
+ name: "transfer",
16
+ type: "function",
17
+ stateMutability: "nonpayable",
18
+ inputs: [
19
+ { name: "to", type: "address" },
20
+ { name: "amount", type: "uint256" },
21
+ ],
22
+ outputs: [{ name: "", type: "bool" }],
23
+ },
24
+ {
25
+ name: "allowance",
26
+ type: "function",
27
+ stateMutability: "view",
28
+ inputs: [
29
+ { name: "owner", type: "address" },
30
+ { name: "spender", type: "address" },
31
+ ],
32
+ outputs: [{ name: "", type: "uint256" }],
33
+ },
34
+ {
35
+ name: "approve",
36
+ type: "function",
37
+ stateMutability: "nonpayable",
38
+ inputs: [
39
+ { name: "spender", type: "address" },
40
+ { name: "amount", type: "uint256" },
41
+ ],
42
+ outputs: [{ name: "", type: "bool" }],
43
+ },
44
+ ] as const
45
+
46
+ export const ERC721_ABI = [
47
+ {
48
+ name: "ownerOf",
49
+ type: "function",
50
+ stateMutability: "view",
51
+ inputs: [{ name: "tokenId", type: "uint256" }],
52
+ outputs: [{ name: "", type: "address" }],
53
+ },
54
+ {
55
+ name: "transferFrom",
56
+ type: "function",
57
+ stateMutability: "nonpayable",
58
+ inputs: [
59
+ { name: "from", type: "address" },
60
+ { name: "to", type: "address" },
61
+ { name: "tokenId", type: "uint256" },
62
+ ],
63
+ outputs: [],
64
+ },
65
+ {
66
+ name: "isApprovedForAll",
67
+ type: "function",
68
+ stateMutability: "view",
69
+ inputs: [
70
+ { name: "owner", type: "address" },
71
+ { name: "operator", type: "address" },
72
+ ],
73
+ outputs: [{ name: "", type: "bool" }],
74
+ },
75
+ {
76
+ name: "getApproved",
77
+ type: "function",
78
+ stateMutability: "view",
79
+ inputs: [{ name: "tokenId", type: "uint256" }],
80
+ outputs: [{ name: "", type: "address" }],
81
+ },
82
+ {
83
+ name: "setApprovalForAll",
84
+ type: "function",
85
+ stateMutability: "nonpayable",
86
+ inputs: [
87
+ { name: "operator", type: "address" },
88
+ { name: "approved", type: "bool" },
89
+ ],
90
+ outputs: [],
91
+ },
92
+ ] as const
93
+
94
+ export const ERC1155_ABI = [
95
+ {
96
+ name: "balanceOf",
97
+ type: "function",
98
+ stateMutability: "view",
99
+ inputs: [
100
+ { name: "account", type: "address" },
101
+ { name: "id", type: "uint256" },
102
+ ],
103
+ outputs: [{ name: "", type: "uint256" }],
104
+ },
105
+ {
106
+ name: "safeTransferFrom",
107
+ type: "function",
108
+ stateMutability: "nonpayable",
109
+ inputs: [
110
+ { name: "from", type: "address" },
111
+ { name: "to", type: "address" },
112
+ { name: "id", type: "uint256" },
113
+ { name: "amount", type: "uint256" },
114
+ { name: "data", type: "bytes" },
115
+ ],
116
+ outputs: [],
117
+ },
118
+ {
119
+ name: "isApprovedForAll",
120
+ type: "function",
121
+ stateMutability: "view",
122
+ inputs: [
123
+ { name: "owner", type: "address" },
124
+ { name: "operator", type: "address" },
125
+ ],
126
+ outputs: [{ name: "", type: "bool" }],
127
+ },
128
+ {
129
+ name: "setApprovalForAll",
130
+ type: "function",
131
+ stateMutability: "nonpayable",
132
+ inputs: [
133
+ { name: "operator", type: "address" },
134
+ { name: "approved", type: "bool" },
135
+ ],
136
+ outputs: [],
137
+ },
138
+ ] as const
139
+
140
+ export const WETH_DEPOSIT_ABI = [
141
+ {
142
+ name: "deposit",
143
+ type: "function",
144
+ stateMutability: "payable",
145
+ inputs: [],
146
+ outputs: [],
147
+ },
148
+ ] as const
149
+
150
+ export const WETH_WITHDRAW_ABI = [
151
+ {
152
+ name: "withdraw",
153
+ type: "function",
154
+ stateMutability: "nonpayable",
155
+ inputs: [{ name: "wad", type: "uint256" }],
156
+ outputs: [],
157
+ },
158
+ ] as const
159
+
160
+ export const TRANSFER_HELPER_ABI = [
161
+ {
162
+ name: "bulkTransfer",
163
+ type: "function",
164
+ stateMutability: "nonpayable",
165
+ inputs: [
166
+ {
167
+ name: "items",
168
+ type: "tuple[]",
169
+ components: [
170
+ { name: "itemType", type: "uint8" },
171
+ { name: "token", type: "address" },
172
+ { name: "identifier", type: "uint256" },
173
+ { name: "amount", type: "uint256" },
174
+ { name: "recipient", type: "address" },
175
+ ],
176
+ },
177
+ { name: "conduitKey", type: "bytes32" },
178
+ ],
179
+ outputs: [{ name: "", type: "bytes4" }],
180
+ },
181
+ ] as const
182
+
183
+ export const MULTICALL3_ABI = [
184
+ {
185
+ name: "aggregate3",
186
+ type: "function",
187
+ stateMutability: "payable",
188
+ inputs: [
189
+ {
190
+ name: "calls",
191
+ type: "tuple[]",
192
+ components: [
193
+ { name: "target", type: "address" },
194
+ { name: "allowFailure", type: "bool" },
195
+ { name: "callData", type: "bytes" },
196
+ ],
197
+ },
198
+ ],
199
+ outputs: [
200
+ {
201
+ name: "returnData",
202
+ type: "tuple[]",
203
+ components: [
204
+ { name: "success", type: "bool" },
205
+ { name: "returnData", type: "bytes" },
206
+ ],
207
+ },
208
+ ],
209
+ },
210
+ ] as const
211
+
212
+ export const SET_APPROVAL_FOR_ALL_ABI = [
213
+ {
214
+ name: "setApprovalForAll",
215
+ type: "function",
216
+ stateMutability: "nonpayable",
217
+ inputs: [
218
+ { name: "operator", type: "address" },
219
+ { name: "approved", type: "bool" },
220
+ ],
221
+ outputs: [],
222
+ },
223
+ ] as const
224
+
225
+ export const APPROVE_ABI = [
226
+ {
227
+ name: "approve",
228
+ type: "function",
229
+ stateMutability: "nonpayable",
230
+ inputs: [
231
+ { name: "spender", type: "address" },
232
+ { name: "amount", type: "uint256" },
233
+ ],
234
+ outputs: [{ name: "", type: "bool" }],
235
+ },
236
+ ] as const
package/src/api/api.ts CHANGED
@@ -1,4 +1,3 @@
1
- import { ethers } from "ethers"
2
1
  import { API_BASE_MAINNET } from "../constants"
3
2
  import type {
4
3
  FulfillmentDataResponse,
@@ -51,6 +50,7 @@ import {
51
50
  type GetEventsArgs,
52
51
  type GetEventsResponse,
53
52
  type GetListingsResponse,
53
+ type GetNFTMetadataResponse,
54
54
  type GetNFTResponse,
55
55
  type GetOffersResponse,
56
56
  type GetOrderByHashResponse,
@@ -930,6 +930,39 @@ export class OpenSeaAPI {
930
930
  return this.accountsAPI.resolveAccount(identifier)
931
931
  }
932
932
 
933
+ /**
934
+ * Get the collection that an NFT belongs to.
935
+ * Useful for multi-contract collections where the token ID disambiguates
936
+ * which collection the NFT belongs to.
937
+ * @param address The NFT contract address.
938
+ * @param identifier The token identifier.
939
+ * @param chain The chain where the NFT is located. Defaults to the chain set in the constructor.
940
+ * @returns The {@link OpenSeaCollection} returned by the API.
941
+ */
942
+ public async getNFTCollection(
943
+ address: string,
944
+ identifier: string,
945
+ chain: Chain = this.chain,
946
+ ): Promise<OpenSeaCollection> {
947
+ return this.nftsAPI.getNFTCollection(address, identifier, chain)
948
+ }
949
+
950
+ /**
951
+ * Get detailed metadata for an NFT including name, description, image, traits,
952
+ * and external links.
953
+ * @param address The NFT contract address.
954
+ * @param tokenId The token identifier.
955
+ * @param chain The chain where the NFT is located. Defaults to the chain set in the constructor.
956
+ * @returns The {@link GetNFTMetadataResponse} returned by the API.
957
+ */
958
+ public async getNFTMetadata(
959
+ address: string,
960
+ tokenId: string,
961
+ chain: Chain = this.chain,
962
+ ): Promise<GetNFTMetadataResponse> {
963
+ return this.nftsAPI.getNFTMetadata(address, tokenId, chain)
964
+ }
965
+
933
966
  /**
934
967
  * Generic fetch method for any API endpoint with automatic rate limit retry
935
968
  * @param apiPath Path to URL endpoint under API
@@ -999,7 +1032,9 @@ export class OpenSeaAPI {
999
1032
  * Fetch from an API Endpoint, sending auth token in headers
1000
1033
  * @param url The URL to fetch
1001
1034
  * @param headers Additional headers to send with the request
1002
- * @param body Optional body to send. If set, will POST, otherwise GET
1035
+ * @param body Optional body to send. HTTP method is inferred: POST if body is
1036
+ * provided (non-nullish), GET otherwise. This covers all OpenSea API
1037
+ * endpoints which only use GET and POST.
1003
1038
  * @param options Request options like timeout and abort signal
1004
1039
  */
1005
1040
  private async _fetch(
@@ -1008,61 +1043,64 @@ export class OpenSeaAPI {
1008
1043
  body?: object,
1009
1044
  options?: RequestOptions,
1010
1045
  ) {
1011
- // Create the fetch request
1012
- const req = new ethers.FetchRequest(url)
1013
-
1014
- // Set the headers
1015
- headers = {
1046
+ const mergedHeaders: Record<string, string> = {
1047
+ // Kept as "opensea-js" for server-side analytics continuity after package rename
1016
1048
  "x-app-id": "opensea-js",
1017
1049
  ...(this.apiKey ? { "X-API-KEY": this.apiKey } : {}),
1050
+ ...(body != null ? { "Content-Type": "application/json" } : {}),
1018
1051
  ...headers,
1019
1052
  }
1020
- for (const [key, value] of Object.entries(headers)) {
1021
- req.setHeader(key, value)
1022
- }
1023
-
1024
- // Set the body if provided
1025
- if (body) {
1026
- req.body = body
1027
- }
1028
1053
 
1029
- // Apply request options
1030
- if (options?.timeout !== undefined) {
1031
- req.timeout = options.timeout
1032
- }
1033
-
1034
- // Set up abort signal handling
1035
- let abortHandler: (() => void) | undefined
1036
- if (options?.signal) {
1037
- if (options.signal.aborted) {
1038
- throw new Error("Request aborted")
1039
- }
1040
- abortHandler = () => req.cancel()
1041
- options.signal.addEventListener("abort", abortHandler)
1042
- }
1043
-
1044
- // Set the throttle params
1045
- req.setThrottleParams({ slotInterval: 1000 })
1046
-
1047
- const sanitizedHeaders = { ...req.headers }
1054
+ const sanitizedHeaders = { ...mergedHeaders }
1048
1055
  delete sanitizedHeaders["X-API-KEY"]
1049
1056
  this.logger(
1050
1057
  `Sending request: ${url} ${JSON.stringify({
1051
- method: body ? "POST" : "GET",
1058
+ method: body != null ? "POST" : "GET",
1052
1059
  headers: sanitizedHeaders,
1053
- body: body ? JSON.stringify(body, null, 2) : undefined,
1060
+ body: body != null ? JSON.stringify(body, null, 2) : undefined,
1054
1061
  })}`,
1055
1062
  )
1056
1063
 
1064
+ // Build abort signal (merge timeout + user-provided signal)
1065
+ let controller: AbortController | undefined
1066
+ let timeoutId: ReturnType<typeof setTimeout> | undefined
1067
+ let userAbortHandler: (() => void) | undefined
1068
+ let signal = options?.signal
1069
+ if (options?.timeout !== undefined) {
1070
+ controller = new AbortController()
1071
+ timeoutId = setTimeout(() => controller!.abort(), options.timeout)
1072
+ // If user provided their own signal, abort ours if theirs fires
1073
+ if (options.signal) {
1074
+ if (options.signal.aborted) {
1075
+ clearTimeout(timeoutId)
1076
+ throw new Error("Request aborted")
1077
+ }
1078
+ userAbortHandler = () => {
1079
+ controller!.abort()
1080
+ clearTimeout(timeoutId)
1081
+ }
1082
+ options.signal.addEventListener("abort", userAbortHandler)
1083
+ }
1084
+ signal = controller.signal
1085
+ } else if (options?.signal?.aborted) {
1086
+ throw new Error("Request aborted")
1087
+ }
1088
+
1057
1089
  try {
1058
- const response = await req.send()
1059
- if (!response.ok()) {
1090
+ const response = await fetch(url, {
1091
+ method: body != null ? "POST" : "GET",
1092
+ headers: mergedHeaders,
1093
+ body: body != null ? JSON.stringify(body) : undefined,
1094
+ signal,
1095
+ })
1096
+
1097
+ if (!response.ok) {
1060
1098
  // Handle rate limit errors (429 Too Many Requests and 599 custom rate limit)
1061
- if (response.statusCode === 599 || response.statusCode === 429) {
1062
- throw this._createRateLimitError(response)
1099
+ if (response.status === 599 || response.status === 429) {
1100
+ throw await this._createRateLimitError(response)
1063
1101
  }
1064
- // If an errors array is returned, throw with the error messages.
1065
- const errors = response.bodyJson?.errors
1102
+ const responseBody = await response.json().catch(() => ({}))
1103
+ const errors = responseBody?.errors
1066
1104
  if (errors?.length > 0) {
1067
1105
  let errorMessage = Array.isArray(errors)
1068
1106
  ? errors.join(", ")
@@ -1071,17 +1109,18 @@ export class OpenSeaAPI {
1071
1109
  errorMessage = JSON.stringify(errors)
1072
1110
  }
1073
1111
  throw new Error(`Server Error: ${errorMessage}`)
1074
- } else {
1075
- // Otherwise, let ethers throw a SERVER_ERROR since it will include
1076
- // more context about the request and response.
1077
- response.assertOk()
1078
1112
  }
1113
+ throw new Error(
1114
+ `Server Error (${response.status}): ${response.statusText}`,
1115
+ )
1079
1116
  }
1080
- return response.bodyJson
1117
+ return response.json()
1081
1118
  } finally {
1082
- // Clean up abort handler
1083
- if (abortHandler && options?.signal) {
1084
- options.signal.removeEventListener("abort", abortHandler)
1119
+ if (timeoutId !== undefined) {
1120
+ clearTimeout(timeoutId)
1121
+ }
1122
+ if (userAbortHandler && options?.signal) {
1123
+ options.signal.removeEventListener("abort", userAbortHandler)
1085
1124
  }
1086
1125
  }
1087
1126
  }
@@ -1097,9 +1136,8 @@ export class OpenSeaAPI {
1097
1136
  * @param response The HTTP response object from the API
1098
1137
  * @returns The retry-after value in seconds (capped at 5 minutes), or undefined if not present or invalid
1099
1138
  */
1100
- private _parseRetryAfter(response: ethers.FetchResponse): number | undefined {
1101
- const retryAfterHeader =
1102
- response.headers["retry-after"] || response.headers["Retry-After"]
1139
+ private _parseRetryAfter(response: Response): number | undefined {
1140
+ const retryAfterHeader = response.headers.get("retry-after")
1103
1141
  if (retryAfterHeader) {
1104
1142
  const trimmed = retryAfterHeader.trim()
1105
1143
 
@@ -1132,21 +1170,24 @@ export class OpenSeaAPI {
1132
1170
 
1133
1171
  /**
1134
1172
  * Creates a rate limit error with status code and retry-after information.
1173
+ * This is async because it attempts to parse the response body. If the body
1174
+ * is malformed JSON, responseBody will be undefined (intentional — the error
1175
+ * itself is more important than the body).
1135
1176
  * @param response The HTTP response object from the API
1136
1177
  * @returns An enhanced Error object with statusCode, retryAfter and responseBody properties
1137
1178
  */
1138
- private _createRateLimitError(
1139
- response: ethers.FetchResponse,
1140
- ): OpenSeaRateLimitError {
1179
+ private async _createRateLimitError(
1180
+ response: Response,
1181
+ ): Promise<OpenSeaRateLimitError> {
1141
1182
  const retryAfter = this._parseRetryAfter(response)
1142
1183
  const error = new Error(
1143
- `${response.statusCode} ${response.statusMessage}`,
1184
+ `${response.status} ${response.statusText}`,
1144
1185
  ) as OpenSeaRateLimitError
1145
1186
 
1146
1187
  // Add status code and retry-after information to the error object
1147
- error.statusCode = response.statusCode
1188
+ error.statusCode = response.status
1148
1189
  error.retryAfter = retryAfter
1149
- error.responseBody = response.bodyJson
1190
+ error.responseBody = await response.json().catch(() => undefined)
1150
1191
  return error
1151
1192
  }
1152
1193
  }
@@ -206,3 +206,19 @@ export const getTopCollectionsPath = () => {
206
206
  export const getResolveAccountPath = (identifier: string) => {
207
207
  return `${API_V2_PREFIX}/accounts/resolve/${identifier}`
208
208
  }
209
+
210
+ export const getNFTCollectionPath = (
211
+ chain: Chain,
212
+ address: string,
213
+ identifier: string,
214
+ ) => {
215
+ return `${API_V2_PREFIX}/chain/${chain}/contract/${address}/nfts/${identifier}/collection`
216
+ }
217
+
218
+ export const getNFTMetadataPath = (
219
+ chain: Chain,
220
+ contractAddress: string,
221
+ tokenId: string,
222
+ ) => {
223
+ return `${API_V2_PREFIX}/metadata/${chain}/${contractAddress}/${tokenId}`
224
+ }
package/src/api/nfts.ts CHANGED
@@ -1,16 +1,21 @@
1
- import type { Chain } from "../types"
1
+ import type { Chain, OpenSeaCollection } from "../types"
2
+ import { collectionFromJSON } from "../utils/converters"
2
3
  import {
3
4
  getContractPath,
4
5
  getListNFTsByAccountPath,
5
6
  getListNFTsByCollectionPath,
6
7
  getListNFTsByContractPath,
8
+ getNFTCollectionPath,
9
+ getNFTMetadataPath,
7
10
  getNFTPath,
8
11
  getRefreshMetadataPath,
9
12
  getValidateMetadataPath,
10
13
  } from "./apiPaths"
11
14
  import type { Fetcher } from "./fetcher"
12
15
  import type {
16
+ GetCollectionResponse,
13
17
  GetContractResponse,
18
+ GetNFTMetadataResponse,
14
19
  GetNFTResponse,
15
20
  ListNFTsResponse,
16
21
  ValidateMetadataResponse,
@@ -141,4 +146,35 @@ export class NFTsAPI {
141
146
  const response = await this.fetcher.post<ValidateMetadataResponse>(path)
142
147
  return response
143
148
  }
149
+
150
+ /**
151
+ * Get the collection that an NFT belongs to.
152
+ * Useful for multi-contract collections where the token ID disambiguates
153
+ * which collection the NFT belongs to.
154
+ */
155
+ async getNFTCollection(
156
+ address: string,
157
+ identifier: string,
158
+ chain: Chain = this.chain,
159
+ ): Promise<OpenSeaCollection> {
160
+ const response = await this.fetcher.get<GetCollectionResponse>(
161
+ getNFTCollectionPath(chain, address, identifier),
162
+ )
163
+ return collectionFromJSON(response)
164
+ }
165
+
166
+ /**
167
+ * Get detailed metadata for an NFT including name, description, image, traits,
168
+ * and external links.
169
+ */
170
+ async getNFTMetadata(
171
+ address: string,
172
+ tokenId: string,
173
+ chain: Chain = this.chain,
174
+ ): Promise<GetNFTMetadataResponse> {
175
+ const response = await this.fetcher.get<GetNFTMetadataResponse>(
176
+ getNFTMetadataPath(chain, address, tokenId),
177
+ )
178
+ return response
179
+ }
144
180
  }
package/src/api/orders.ts CHANGED
@@ -207,8 +207,8 @@ export class OrdersAPI {
207
207
  }
208
208
 
209
209
  // Validate side value
210
- if (side !== "ask" && side !== "bid") {
211
- throw new Error("side must be either 'ask' or 'bid'")
210
+ if (side !== "listing" && side !== "offer") {
211
+ throw new Error("side must be either 'listing' or 'offer'")
212
212
  }
213
213
 
214
214
  // Validate protocolAddress format
package/src/api/types.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import type { AssetMetadataResponse } from "@opensea/api-types"
1
2
  import type { ConsiderationItem } from "@opensea/seaport-js/lib/types"
2
3
  import type {
3
4
  OrderType,
@@ -1208,3 +1209,10 @@ export type ValidateMetadataResponse = {
1208
1209
  statusCode?: number
1209
1210
  }
1210
1211
  }
1212
+
1213
+ /**
1214
+ * Response from OpenSea API for fetching raw NFT metadata.
1215
+ * Derived from the generated OpenAPI spec type to stay in sync automatically.
1216
+ * @category API Response Types
1217
+ */
1218
+ export type GetNFTMetadataResponse = AssetMetadataResponse
package/src/constants.ts CHANGED
@@ -1,12 +1,16 @@
1
- import { FixedNumber } from "ethers"
2
-
3
1
  // =============================================================================
4
2
  // Math & Calculation Constants
5
3
  // =============================================================================
6
4
 
7
- export const FIXED_NUMBER_100 = FixedNumber.fromValue(100)
8
5
  export const INVERSE_BASIS_POINT = 10_000n // 100 basis points per 1%
9
6
 
7
+ // =============================================================================
8
+ // Ethereum Constants
9
+ // =============================================================================
10
+
11
+ export const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000"
12
+ export const MAX_UINT256 = 2n ** 256n - 1n
13
+
10
14
  // =============================================================================
11
15
  // API Configuration
12
16
  // =============================================================================