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

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 viem
import { 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-1155

Query 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