Docs
OpenSea

Swap Tokens

Build a token swap using the OpenSea API and SDK.

Use the OpenSea API to swap tokens across chains, with 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, 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 { base } from "viem/chains";
import { OpenSeaSDK, Chain } from "@opensea/sdk/viem";

const publicClient = createPublicClient({ chain: base, transport: http("https://your-rpc-url") });
const walletClient = createWalletClient({ chain: base, transport: http("https://your-rpc-url"), account: "0x..." });

const sdk = new OpenSeaSDK(
  { publicClient, walletClient },
  { chain: Chain.Base, 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.

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

The SDK takes these parameters in camelCase (fromChain, fromAddress, toChain, toAddress). The raw REST endpoint shown in the curl example uses the snake_case names above.

SDK

const quote = await sdk.api.getSwapQuote({
  fromChain: "base",
  fromAddress: "0x0000000000000000000000000000000000000000", // native ETH
  toChain: "base",
  toAddress: "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.

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

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

Cross-chain swaps

Cross-chain swaps work the same way. Specify a different toChain and the API handles bridging automatically.

const crossChainQuote = await sdk.api.getSwapQuote({
  fromChain: "ethereum",
  fromAddress: "0x0000000000000000000000000000000000000000",
  toChain: "base",
  toAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  quantity: "0.1",
  address: "0xYOUR_WALLET_ADDRESS",
});

Cross-chain swaps may return multiple transactions (e.g. an approval and 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