Docs
OpenSea

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.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.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 before deploying or updating.

SDK

const validation = await sdk.api.validateNFTMetadata(
  "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