Docs
OpenSea

Swap Tokens

Build a token swap using the OpenSea API and SDK.

Use the OpenSea API to swap tokens across chains — no manual bridging required. This guide covers getting a quote, executing the swap, and discovering tokens.

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.Base,
  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.

Step 1: Discover Tokens

Before swapping, you can discover which tokens are available using the trending and top token endpoints.

SDK

// Get trending tokens (sorted by 24h price change)
const trending = await sdk.api.getTrendingTokens();
console.log(trending);

// Get top tokens by volume
const top = await sdk.api.getTopTokens();
console.log(top);

curl

# Trending tokens
curl -X GET "https://api.opensea.io/api/v2/tokens/trending" \
  -H "X-API-KEY: YOUR_API_KEY"

# Top tokens
curl -X GET "https://api.opensea.io/api/v2/tokens/top" \
  -H "X-API-KEY: YOUR_API_KEY"

Step 2: Check Your Balance

Confirm your wallet holds enough of the source token.

SDK

const balances = await sdk.api.getAccountTokens("0xYOUR_WALLET_ADDRESS");
console.log(balances);

curl

curl -X GET "https://api.opensea.io/api/v2/account/0xYOUR_WALLET_ADDRESS/tokens" \
  -H "X-API-KEY: YOUR_API_KEY"

Step 3: Get a Swap Quote

Request a quote to see the estimated output amount, price impact, fees, and the transaction data needed to execute the swap.

Parameters:

ParameterDescription
from_chainSource chain (e.g., base)
from_addressToken contract address to sell (use 0x0000000000000000000000000000000000000000 for native ETH)
to_chainDestination chain (e.g., base, or a different chain for cross-chain)
to_addressToken contract address to buy
quantityAmount to swap in native units (e.g., 0.02 for 0.02 ETH)
addressYour wallet address (the taker)
slippage(Optional) Maximum slippage tolerance

SDK

const quote = await sdk.api.getSwapQuote({
  from_chain: "base",
  from_address: "0x0000000000000000000000000000000000000000", // native ETH
  to_chain: "base",
  to_address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
  quantity: "0.02",
  address: "0xYOUR_WALLET_ADDRESS",
});

console.log("Quote:", quote);
// quote.transactions contains the transaction(s) to execute

curl

curl -X GET "https://api.opensea.io/api/v2/swap/quote?\
from_chain=base&\
from_address=0x0000000000000000000000000000000000000000&\
to_chain=base&\
to_address=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&\
quantity=0.02&\
address=0xYOUR_WALLET_ADDRESS" \
  -H "X-API-KEY: YOUR_API_KEY"

The response includes a transactions array. Each transaction contains:

  • chain — the chain to submit the transaction on
  • to — the target contract address
  • data — hex-encoded calldata
  • value — native token value to send (if any)

Step 4: Execute the Swap

Use the transaction data from the quote response to submit the swap onchain.

const signer = await provider.getSigner();

for (const tx of quote.transactions) {
  const transaction = await signer.sendTransaction({
    to: tx.to,
    data: tx.data,
    value: tx.value ? BigInt(tx.value) : 0n,
  });

  console.log("Transaction hash:", transaction.hash);
  const receipt = await transaction.wait();
  console.log("Confirmed in block:", receipt.blockNumber);
}

Cross-Chain Swaps

Cross-chain swaps work the same way — just specify a different to_chain. The API handles bridging automatically.

const crossChainQuote = await sdk.api.getSwapQuote({
  from_chain: "ethereum",
  from_address: "0x0000000000000000000000000000000000000000",
  to_chain: "base",
  to_address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  quantity: "0.1",
  address: "0xYOUR_WALLET_ADDRESS",
});

Cross-chain swaps may return multiple transactions (e.g., an approval + a bridge transaction). Execute them in order.

CLI

The OpenSea CLI supports swap quotes directly:

opensea swaps quote \
  --from-chain base \
  --from-address 0x0000000000000000000000000000000000000000 \
  --to-chain base \
  --to-address 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  --quantity 0.02 \
  --address 0xYOUR_WALLET_ADDRESS

Next Steps

Updated 1 day ago