---
name: use-clanker-sdk
description: Launch V5 tokens with the Clanker SDK, and manage existing V3, V4, and V5 tokens. Use when the user asks to deploy a token, create a coin, launch a token, add a creator buy, set taxes, burn, dividends, or integrator shares, claim rewards, update reward recipients or admins, update token metadata, claim vaulted tokens or airdrops, or manage an existing presale.
---

# Using the Clanker SDK

## Overview

`clanker-sdk/v5` launches V5 tokens. A V5 token has a buy tax and a sell tax. The tax pays the reward slots, and it can also pay a burn, dividends to holders, and an integrator.

From version 5, the SDK launches V5 tokens only. `deploy`, `deploySimulate`, and `getDeployTransaction` of `clanker-sdk/v3` and `clanker-sdk/v4` throw, and so does `startPresale`. Use the V3 and V4 clients only to manage existing tokens.

On clanker.world, every new launch is a V5 token: the deploy page, the partner API, the X and Farcaster bot, and group clanks. New V4 launches, new presales, vaults, airdrops, and custom fee configs at launch are no longer available. Managing existing V3 and V4 tokens is unchanged: claims, rewards, metadata, vault and airdrop claims, and presales that are already running.

The full V5 reference is `docs/v5.md` in the clanker-sdk repo, and the SDK v5 page at https://www.clanker.world/docs/sdk-reference/v5.

## Installation

```bash
npm install clanker-sdk viem
```

Version 5 requires viem 2.49.3 or newer. viem is a peer dependency, so the SDK uses your viem copy, and an older viem gives a peer dependency error on install.

## Supported Chains

| Chain           | ID    | Import                         | Creator buy                                                     |
| --------------- | ----- | ------------------------------ | --------------------------------------------------------------- |
| Base            | 8453  | `base` from `viem/chains`      | Native coin and USDC                                            |
| BNB Chain       | 56    | `bsc` from `viem/chains`       | Native coin and USDC                                            |
| Monad           | 143   | `monad` from `viem/chains`     | Native coin and USDC                                            |
| X Layer         | 196   | `xLayer` from `viem/chains`    | Native coin and USDC                                            |
| Robinhood Chain | 4663  | `robinhood` from `clanker-sdk` | Native coin and USDG                                            |
| Arc             | 5042  | `arc` from `viem/chains`       | USDC, the native coin of Arc                                    |
| Elysium         | 99901 | `elysium` from `clanker-sdk`   | HYPE (the native coin). A USDC creator buy needs a custom route |

Launches are open on Base, BNB Chain, Monad, X Layer, Robinhood Chain, Arc, and Elysium. Clanker no longer supports new launches on Ethereum, Arbitrum, and Unichain: their factories have launches turned off, so a launch there fails with `Launches are not open on chain <id>.` before anything is sent.

Elysium needs clanker-sdk 5.1.0 or newer. It is not in viem and has no public RPC. Import `elysium` from `clanker-sdk` and pass your own RPC URL, for example `http('<your Elysium RPC URL>')`.

## Quick Start

```typescript
import { Clanker } from 'clanker-sdk/v5';
import {
  createPublicClient,
  createWalletClient,
  http,
  type PublicClient,
} from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const publicClient = createPublicClient({
  chain: base,
  transport: http(),
}) as PublicClient;
const wallet = createWalletClient({ account, chain: base, transport: http() });

const clanker = new Clanker({ wallet, publicClient });

const { txHash, waitForTransaction, error } = await clanker.deploy({
  name: 'My Token',
  symbol: 'TKN',
  image: 'ipfs://...',
  devBuy: { ethAmount: '0.01' },
});
if (error) throw error;

const result = await waitForTransaction();
if (result.error) throw result.error;
console.log(txHash, result.address, result.poolId);
```

`wallet` and `publicClient` must use the same chain.

## Imports

```typescript
// V5: launches and V5 token management
import {
  BASE_USDC,
  Clanker,
  TAX_ADDRESSES,
  type ClankerTokenV5,
} from 'clanker-sdk/v5';

// V4 and V3: management of existing tokens only
import { Clanker as ClankerV4 } from 'clanker-sdk/v4';
import { Clanker as ClankerV3 } from 'clanker-sdk/v3';

// V4 extensions for existing tokens and presales
import {
  fetchAirdropProofs,
  claimAirdrop,
  buyIntoPresale,
  endPresale,
  claimTokens,
} from 'clanker-sdk/v4/extensions';
```

## V5 Token Configuration

| Field                          | Default          | Description                                                                                               |
| ------------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------- |
| `name`, `symbol`               | required         | Token name and symbol                                                                                     |
| `image`, `metadata`, `context` | empty            | The same fields as V4                                                                                     |
| `tokenAdmin`                   | the caller       | The creator of the token                                                                                  |
| `buyFee`, `sellFee`            | `1`              | Total tax percentage. Each includes the protocol fee. The factory sets the bounds                         |
| `pool.pairedToken`             | the native coin  | `'WETH'` also means the native coin. On Arc both mean USDC. Another quote must be admitted by the factory |
| `burn`                         | `0`              | Percentage of the tax to burn                                                                             |
| `dividends`                    | none             | `{ share, minimumHolding }`. `minimumHolding` uses token base units with 18 decimals                      |
| `integrator`                   | none             | `{ address, share }`                                                                                      |
| `rewards.recipients`           | one creator slot | One to seven slots with bps that total 10000. `token` is `'Paired'` or omitted                            |
| `devBuy`                       | none             | `{ ethAmount, recipient?, minAmountOut?, poolKey?, routeData? }`                                          |

`burn`, `dividends.share`, and `integrator.share` divide the tax after the protocol share, and their total must not be more than 100%. The creator gets the rest.

V5 rejects these V4 fields: `fee`, `fees`, `salt`, `vault`, `airdrop`, `presale`, `sniperFees`, pool positions and presets, custom ticks, lockers, pool extensions, and the `Both` and `Clanker` reward tokens. `vanity` is accepted and has no effect.

### Creator Buy

```typescript
devBuy: { ethAmount: '0.01' }                    // native coin
pool: { pairedToken: BASE_USDC }, devBuy: { ethAmount: '0.01' }  // stable quote on Base
```

- The SDK selects the route for the native quote and for the stable quote of each chain. Another quote needs `routeData` or `buildBuyRoute`. On Elysium, only HYPE has an SDK route, so a USDC creator buy needs `routeData` or `buildBuyRoute`.
- The SDK simulates the launch and sets `minAmountOut` 5% below the quote. Set `devBuySlippagePercent` in the second argument of `deploy` to change it.
- The contract sends the bought tokens to the caller. If `devBuy.recipient` or `tokenAdmin` is another address, `deploy` sends them in a second transaction and returns `transferTxHash`.

A top-level `error` from `deploy` means that nothing was sent, unless its `data.rawName` is `SEND_UNCERTAIN` (the send itself failed, so the launch can exist; check the wallet's transactions before a retry). After the launch is sent, `deploy` returns no top-level `error`: check `waitForTransaction` for the launch, and `transferError` with `failedStep` for a failed recipient transfer.

Warning: do not repeat a `deploy` call after a result that has a `txHash`. The launch can exist, and a second call launches a second token.

## Managing Tokens

The V5 client uses the V4 method names. Each write returns `{ txHash, error }`.

```typescript
await clanker.claimRewards({ token: '0x...', rewardRecipient: '0x...' });
await clanker.availableRewards({ token: '0x...', rewardRecipient: '0x...' });
await clanker.getTokenRewards({ token: '0x...' });
await clanker.updateRewardRecipient({
  token: '0x...',
  rewardIndex: 0n,
  newRecipient: '0x...',
});
await clanker.updateRewardAdmin({
  token: '0x...',
  rewardIndex: 1n,
  newAdmin: '0x...',
});
await clanker.updateImage({ token: '0x...', newImage: 'ipfs://...' });
await clanker.updateMetadata({
  token: '0x...',
  metadata: JSON.stringify({ description: 'New' }),
});
```

- V5 rewards: a claim pays the whole balance of the recipient for one currency, across all pools.
- The creator slot admin follows creator rights. Use `proposeCreatorRightsTransfer` to change it.
- `getTokenRewards` returns `rewardIsCreator`, which marks the creator slot. `safeTransferCreatorRights({ token, receiver, callbackData, value })` moves creator rights to a contract in one step.
- Dividends: `withdrawableDividends({ token, holder })`, and `claimDividends({ tokens, unwrapWrappedNative })` for up to 64 tokens in one transaction (native coin by default; `unwrapWrappedNative: false` pays the wrapped token). `withdrawDividends({ dividend })` claims from one dividend contract. `dividendOf(token)` returns the dividend contract of a token.
- Reads: `taxPolicy()` and `launchCreationEnabled()` for the factory settings, `getPoolConfig({ token })` for the stored launch, and `getTaxRates({ token, isBuy })` for the live tax, including the anti-snipe surcharge. `getTaxRates` uses a 1e24 scale: 1% is `10n ** 22n`.
- Integrators claim with `claimRewards({ token, rewardRecipient: integrator })`.
- Each V5 write has matching `get…Transaction` and `…Simulate` methods.
- CLI: `clanker-sdk dividends available --token <TOKEN>` and `clanker-sdk dividends claim --token <TOKEN>` check and claim holder dividends.
- CLI `deploy`: exit code 1 means the launch failed or nothing was sent. Exit code 2 (`success: false` in `--json` mode) means the launch exists or can exist and the send or a later step failed. Do not run the command again after exit code 2, because that can launch a second token. Check the transaction first.
- The protocol takes 10% of the tax, at least 0.5% and at most 1% of the trade. At the default 1% tax it takes half the tax.

For an existing V4 token, use `clanker-sdk/v4` with the same method names, plus `claimVaultedTokens`. For an existing presale, use the presale functions in `clanker-sdk/v4/extensions`. New presales are closed.

## Error Handling Pattern

```typescript
const { txHash, waitForTransaction, error } = await clanker.deploy(config);
if (error) throw error;
const result = await waitForTransaction();
if (result.error) throw result.error;
```

A failure before submission returns `{ error }` and sends nothing, except an error with `data.rawName` `SEND_UNCERTAIN`, where the launch can exist. After the launch is sent, `deploy` returns no top-level `error`; check `waitForTransaction` and `transferError`. A missing client or an invalid token configuration throws.

## Environment Variables

| Variable      | Required | Description                                                       |
| ------------- | -------- | ----------------------------------------------------------------- |
| `PRIVATE_KEY` | Yes      | Wallet private key (0x-prefixed)                                  |
| `RPC_URL`     | No       | Custom RPC endpoint. Required on Elysium, which has no public RPC |

## Additional Resources

- V5 reference: `docs/v5.md` in the clanker-sdk repo
- V5 examples: the examples/v5/ directory in the clanker-sdk repo
- Management of existing V4 tokens: examples/v4/
- Existing presales: examples/v4/presale/

## V5 launches

Use `POST /api/tokens/deploy`. Every launch is a V5 token: `protocol` defaults to `"v5"`, and a request without `tax` launches with a 1% buy tax and a 1% sell tax.
The existing token fields and partner authentication still apply. `tax: { buyFee, sellFee }` sets each rate as the total trade tax in percent, including the protocol fee.
Optional Tax fields are `dividends`, `burn`, `minimumDividendHolding`, `antiSnipeEnabled`, `integrator`, and `metadataEditable`.
The holder minimum uses a whole-token decimal string. Shares specify percentages after the protocol fee.
`integrator: { address, share }` gives an integrator a share of the tax (the default share is 0). Burn, dividends, and the integrator share together must not exceed 100. `metadataEditable` (default `true`) lets the creator change the image and metadata after launch, and verify the token.
The V5 request fields are `token` (`name`, `symbol`, `image`, `tokenAdmin`, `description`, `socialMediaUrls`, `auditUrls`, `requestKey`), `tax`, `rewards` (`recipient`, `admin`, `allocation`; `rewardsToken` is `Paired` or omitted), `pool.pairedToken`, `chainId`, `context`, and `dryRun`. Droids are retired: the old `agent` and `legionFundingRecipient` fields are accepted and ignored.
V4 launches are closed. `protocol: "v4"` and the V4-only fields return 400 with the field list in `fields`: `fees`, `vault`, `airdrop`, `poolExtension`, `devBuy`, a `pool` field other than `pairedToken` (such as `pool.type` or `pool.initialMarketCap`), and a `rewardsToken` other than `Paired`. `POST /api/tokens/deploy/v4` returns 410.
`GET /api/metadata/factories` gives the current V5 policy: `launchCreationEnabled`, the rate bounds, the protocol fee, the sniper tax, and the minimum dividend holding.
V5 requires an active, configured factory with `launchCreationEnabled` true. When it is false (launches are not open yet or the owner paused them), the deploy returns 400 with "V5 launches are not open yet."
`chainId` selects Base, BNB Chain (56), Monad (143), Robinhood Chain (4663), X Layer (196), Arc (5042), or Elysium (99901). A chain must be open for V5. The default `pool.pairedToken` is the native coin; the chain's stable (USDC, or USDG on Robinhood Chain) also works, and Base accepts the other quotes that its V5 factory registers. Arc has no native pool, so the default there is USDC. On Elysium, the API accepts only the native coin (HYPE).
V5 reward recipients receive the pair token: native ETH for an ETH pair, and the quote token for another pair. Use `dryRun: true` to simulate without a deployment.
For V5 tokens, the fee-history APIs read the V5 hook and FeeEscrow events. The FeeEscrow holds one balance per recipient and currency for all V5 tokens, and a claim pays the whole balance. The fees and claimed-fees APIs split each claim to the token; creator earnings show the whole balance that a claim pays.
The SDK calls above manage V5 tokens with `clanker-sdk/v5`. The token admin page (`https://clanker.world/clanker/<token address>/admin`) can also claim fees, update the image and metadata, verify the token, and change the reward recipients and admins.
A V5 token has no `verify()`. To verify it, the current creator calls the factory `updateTokenExtraMetadata(token, "verified", "true")`. Only the exact value `true`, written after the launch, shows the Verified badge. A value from the launch metadata does not count.
