ourzora/zora-protocol/public

Zora Coins SDK Skill

SDK version: @zoralabs/coins-sdk@0.5.2 | Network: Base mainnet (8453) | Testnet: Base Sepolia (84532)

You are an AI assistant helping developers build on the Zora Coins Protocol. Use this reference to guide implementation. Link to docs.zora.co for full code examples.

When to Use What

Protocol Overview

ZORA Coins are ERC-20 media coins on Base (chain ID 8453). Every coin has a Uniswap V4 pool with locked liquidity, automatic reward distribution, and sniper protection.

Chain support:

• Base mainnet (8453) — Production. All features available.
• Base Sepolia (84532) — Testnet. ZORA, CREATOR_COIN, and CREATOR_COIN_OR_ZORA currencies are NOT available on Sepolia.

Coin types:

Fee distribution (creator/content coins, 1% total):

All rewards are converted to the backing currency and distributed automatically on every swap.

Sniper tax: 99% fee at launch, decaying linearly to the base fee over 10 seconds.

SDK Setup

Install: npm install @zoralabs/coins-sdk viem

Configure API key (recommended to avoid rate limiting and to get more accurate coin valuations via getProfileBalances):

import { setApiKey } from "@zoralabs/coins-sdk";
setApiKey("your-api-key-here");

Get an API key at https://zora.co/settings/developer

Full setup guide: https://docs.zora.co/coins/sdk

Creating Coins

Functions: createCoin() (high-level, sends tx) and createCoinCall() (low-level, returns raw calldata)

Parameters (`CreateCoinArgs`):

`ContentCoinCurrency` enum values:

"CREATOR_COIN"; // Back with creator's coin
"CREATOR_COIN_OR_ZORA"; // Creator coin if exists, otherwise ZORA
"ZORA"; // Back with ZORA token
"ETH"; // Back with ETH

Note: CREATOR_COIN, CREATOR_COIN_OR_ZORA, and ZORA are NOT available on Base Sepolia.

`StartingMarketCap` values: LOW (default, most coins) or HIGH (known creators/brands, higher initial price to prevent sniping)

Returns (`createCoin`): { hash, receipt, address, deployment, chain }

Returns (`createCoinCall`): { calls: [{ to, data, value }], predictedCoinAddress }

Metadata builder — upload assets and produce a URI:

import {
  createMetadataBuilder,
  createZoraUploaderForCreator,
} from "@zoralabs/coins-sdk";
const { createMetadataParameters } = await createMetadataBuilder()
  .withName("My Coin")
  .withSymbol("MC")
  .withDescription("Description")
  .withImage(imageFile)
  .upload(createZoraUploaderForCreator(creatorAddress));

Extract deployment from logs (for custom tx flows):

import { getCoinCreateFromLogs } from "@zoralabs/coins-sdk";
const coinDeployment = getCoinCreateFromLogs(receipt);

Full docs: https://docs.zora.co/coins/sdk/create-coin Metadata builder: https://docs.zora.co/coins/sdk/metadata-builder

Trading Coins

Functions: tradeCoin() (full flow with permits) and createTradeCall() (direct ETH trades)

Parameters (`TradeParameters`):

Supported swaps: ETH <-> ERC20, Creator Coin <-> Creator Coin, Content Coin <-> Creator Coin, ERC20 <-> ERC20

The SDK automatically handles permit signatures (EIP-2612 via permit2) to avoid separate approval transactions. Only EOA wallets are supported (smart wallet support coming soon).

Network: Base mainnet only.

Full docs: https://docs.zora.co/coins/sdk/trade-coin

Updating Coins

Functions: updateCoinURI() and setPayoutRecipient() (owner-only)

• updateCoinURI({ coin, newURI }) — Update metadata URI (IPFS preferred)
• setPayoutRecipient({ coin, newPayoutRecipient }) — Change reward recipient

Non-owners receive an OnlyOwner revert.

Full docs: https://docs.zora.co/coins/sdk/update-coin

Querying Coins

Coin data

Profile data

Explore

All explore functions accept optional count and after for cursor-based pagination.

Trend coins

Full docs: https://docs.zora.co/coins/sdk/queries

Common Patterns

Create a coin with metadata upload

// 1. Build and upload metadata
const { createMetadataParameters } = await createMetadataBuilder()
  .withName("My Coin")
  .withSymbol("MC")
  .withDescription("A coin")
  .withImage(imageFile)
  .upload(createZoraUploaderForCreator(creatorAddress));
// 2. Create the coin (spreads name, symbol, uri from metadata)
const result = await createCoin({
  call: {
    ...createMetadataParameters,
    creator: creatorAddress,
    currency: "ZORA",
    chainId: 8453,
  },
  walletClient,
  publicClient,
});
// 3. Verify deployment
const coin = await getCoin({ address: result.address });

Look up a coin, then buy it

// 1. Look up the coin
const { data } = await getCoin({ address: coinAddress });
console.log(data.zora20Token.marketCap);
// 2. Buy with ETH
const receipt = await tradeCoin({
  tradeParameters: {
    sell: { type: "eth" },
    buy: { type: "erc20", address: coinAddress },
    amountIn: parseEther("0.01"),
    slippage: 0.05,
    sender: account.address,
  },
  walletClient,
  account,
  publicClient,
});

Paginate through results