Transfer and manage NFTs
Programmatically transfer, manage, and validate NFTs using the OpenSea SDK.
The OpenSea SDK (@opensea/sdk) provides methods for transferring NFTs, managing approvals, checking balances, and maintaining metadata. This guide covers common portfolio management operations.
Prerequisites
- Node.js >= 20.0.0
- OpenSea API key (get one here, or use the instant API key endpoint)
- viem (v2+). ethers.js (v6+) is also supported.
- A wallet with NFTs to manage
Security Warning: Do not use the SDK in client-side code, since your API key would be exposed. Use it on a backend server and return transaction data to your frontend.
Setup
npm install @opensea/sdk viemimport { createPublicClient, createWalletClient, http } from "viem";
import { mainnet } from "viem/chains";
import { OpenSeaSDK, Chain } from "@opensea/sdk/viem";
const publicClient = createPublicClient({ chain: mainnet, transport: http("https://your-rpc-url") });
const walletClient = createWalletClient({ chain: mainnet, transport: http("https://your-rpc-url"), account: "0x..." });
const sdk = new OpenSeaSDK(
{ publicClient, walletClient },
{ chain: Chain.Mainnet, apiKey: "YOUR_API_KEY" },
);The examples below use viem. The SDK also supports ethers.js (v6+); see Buy and sell NFTs for the ethers setup. All SDK methods work the same with either library.
Single transfer
Transfer an NFT from one wallet to another.
import { TokenStandard } from "@opensea/sdk";
const txHash = await sdk.transfer({
asset: {
tokenAddress: "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
tokenId: "1234",
tokenStandard: TokenStandard.ERC721,
},
fromAddress: "0xSENDER_ADDRESS",
toAddress: "0xRECIPIENT_ADDRESS",
});
console.log("Transfer tx:", txHash);Bulk transfer
Transfer multiple NFTs in a single operation. Each asset can go to a different recipient.
import { TokenStandard } from "@opensea/sdk";
const txHash = await sdk.bulkTransfer({
assets: [
{
asset: {
tokenAddress: "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
tokenId: "1234",
tokenStandard: TokenStandard.ERC721,
},
toAddress: "0xRECIPIENT_A",
},
{
asset: {
tokenAddress: "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
tokenId: "5678",
tokenStandard: TokenStandard.ERC721,
},
toAddress: "0xRECIPIENT_B",
},
],
fromAddress: "0xSENDER_ADDRESS",
});
console.log("Bulk transfer tx:", txHash);Batch approvals
Approve multiple asset contracts at once so they can be transferred or listed without individual approval transactions.
import { TokenStandard } from "@opensea/sdk";
await sdk.batchApproveAssets({
assets: [
{
asset: {
tokenAddress: "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
tokenId: "1234",
tokenStandard: TokenStandard.ERC721,
},
},
{
asset: {
tokenAddress: "0xBd3531dA5CF5857e7CfAA92426877b022e612cf8",
tokenId: "5678",
tokenStandard: TokenStandard.ERC721,
},
},
],
fromAddress: "0xYOUR_WALLET_ADDRESS",
});
console.log("Assets approved");Check balances
Check the balance of a specific asset for an account.
import { TokenStandard } from "@opensea/sdk";
const balance = await sdk.getBalance({
accountAddress: "0xYOUR_WALLET_ADDRESS",
asset: {
tokenAddress: "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
tokenId: "1234",
tokenStandard: TokenStandard.ERC721,
},
});
console.log("Balance:", balance); // 1n for ERC-721, or quantity for ERC-1155Query owned NFTs
Retrieve all NFTs owned by an account.
SDK
const owned = await sdk.api.nfts.getNFTsByAccount("0xYOUR_WALLET_ADDRESS", 50);
for (const nft of owned.nfts) {
console.log(nft.name, nft.identifier, nft.collection);
}curl
curl -X GET "https://api.opensea.io/api/v2/chain/ethereum/account/0xYOUR_WALLET_ADDRESS/nfts?limit=50" \
-H "X-API-KEY: YOUR_API_KEY"Refresh metadata
Trigger a metadata refresh for an NFT. Use this after updating the token URI or metadata on your server.
SDK
await sdk.api.nfts.refreshNFTMetadata(
"0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
"1234",
);
console.log("Metadata refresh triggered");curl
curl -X POST "https://api.opensea.io/api/v2/chain/ethereum/contract/0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/nfts/1234/refresh" \
-H "X-API-KEY: YOUR_API_KEY"Metadata refreshes are processed asynchronously. It may take a few minutes for changes to appear on OpenSea.
Validate metadata
Check whether your NFT metadata is valid and well-formed. The endpoint reads the token's metadata from the chain without OpenSea's cache, so run it after you deploy or update the token URI and before you rely on OpenSea's cached copy.
SDK
const validation = await sdk.api.nfts.validateMetadata(
"0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
"1234",
);
console.log("Valid:", validation);curl
curl -X POST "https://api.opensea.io/api/v2/chain/ethereum/contract/0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/nfts/1234/validate-metadata" \
-H "X-API-KEY: YOUR_API_KEY"Next steps
- Buy and sell NFTs: list and sell your NFTs
- Collection offers and advanced trading: collection offers, bulk listings, and cancellation
- Display an NFT: show NFTs on a website
- @opensea/sdk on GitHub
- buy-sell-opensea-sdk-demo
Updated 16 days ago