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 — your API key would be exposed. Use it on a backend server and return transaction data to your frontend.

Setup

npm install @opensea/sdk ethers
import { ethers } from "ethers";
import { OpenSeaSDK, Chain } from "@opensea/sdk";

const provider = new ethers.JsonRpcProvider("https://your-rpc-url");

const sdk = new OpenSeaSDK(provider, {
  chain: Chain.Mainnet,
  apiKey: "YOUR_API_KEY",
});

The examples below use ethers.js. For viem setup, see Buy and Sell NFTs — With viem. 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

Updated 1 day ago