@clawnch/clawncher-sdk

TypeScript SDK for Clawncher - deploy tokens on Base with Uniswap V4 pools, MEV protection, and configurable fee distribution.

Installation

npm install @clawnch/clawncher-sdk viem

Quick Start - Token Deployment

import { ClawnchDeployer } from '@clawnch/clawncher-sdk';
import { createWalletClient, createPublicClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { baseSepolia } from 'viem/chains';

const account = privateKeyToAccount('0x...');
const wallet = createWalletClient({
  account,
  chain: baseSepolia,
  transport: http(),
});
const publicClient = createPublicClient({
  chain: baseSepolia,
  transport: http(),
});

const deployer = new ClawnchDeployer({
  wallet,
  publicClient,
  network: 'sepolia', // or 'mainnet'
});

const result = await deployer.deploy({
  name: 'My Token',
  symbol: 'MYTKN',
  tokenAdmin: account.address,
  rewards: {
    recipients: [{
      recipient: account.address,
      admin: account.address,
      bps: 10000, // 100%
      feePreference: 'Paired', // Receive fees in WETH
    }],
  },
});

const { address } = await result.waitForTransaction();
console.log('Token deployed:', address);

Deployment Options

Basic Deployment

const result = await deployer.deploy({
  name: 'My Token',
  symbol: 'MYTKN',
  tokenAdmin: account.address,
  image: 'https://example.com/logo.png',
  metadata: {
    description: 'A great token',
    socialMediaUrls: [{ platform: 'twitter', url: 'https://twitter.com/mytoken' }],
  },
  rewards: {
    recipients: [{
      recipient: account.address,
      admin: account.address,
      bps: 10000,
      feePreference: 'Paired',
    }],
  },
});

With Vault (Token Lockup + Vesting)

const result = await deployer.deploy({
  // ... basic options ...
  vault: {
    percentage: 10,              // 10% of supply
    lockupDuration: 7 * 24 * 60 * 60,   // 7 days (minimum)
    vestingDuration: 30 * 24 * 60 * 60, // 30 days linear vesting after lockup
    recipient: account.address,
  },
});

With Dev Buy (Instant)

Buy tokens at launch with ETH - tokens sent directly to recipient:

import { parseEther } from 'viem';

const result = await deployer.deploy({
  // ... basic options ...
  devBuy: {
    ethAmount: parseEther('0.1'),  // Spend 0.1 ETH
    recipient: account.address,    // Tokens sent immediately
  },
});

Multiple Reward Recipients

const result = await deployer.deploy({
  // ... basic options ...
  rewards: {
    recipients: [
      {
        recipient: creatorAddress,
        admin: creatorAddress,
        bps: 8000, // 80%
        feePreference: 'Paired',
      },
      {
        recipient: platformAddress,
        admin: platformAddress,
        bps: 2000, // 20%
        feePreference: 'Paired',
      },
    ],
  },
});

Fee Structure

1% LP fee per swap

• 80% to deployer/reward recipients
• 20% protocol (in WETH)

Fee Preferences

• 'Clawnch' - Receive fees in the deployed token (default)
• 'Paired' - Receive fees in WETH
• 'Both' - Receive fees in both tokens

Vanity Addresses

Vanity addresses (0xb07 suffix) are handled by Clanker's remote service. Pass vanity: true (default) or vanity: false to disable.

Extension Constraints

| Extension | Min | Max | Notes | |-----------|-----|-----|-------| | Vault | 1% | 90% | Lockup min 7 days | | Dev Buy | > 0 ETH | - | Instant transfer | | Airdrop | 1% | 90% | Lockup min 1 day |

Reading On-Chain Data

Use ClawnchReader to read token data directly from the blockchain:

import { ClawnchReader } from '@clawnch/clawncher-sdk';
import { createPublicClient, http } from 'viem';
import { base } from 'viem/chains';

const publicClient = createPublicClient({
  chain: base,
  transport: http(),
});

const reader = new ClawnchReader({
  publicClient,
  network: 'mainnet', // or 'sepolia'
});

// Get full token details (deployment, rewards, vault, vesting, MEV config)
const details = await reader.getTokenDetails('0xTokenAddress');

// Get vault allocation (lockup + vesting)
const vault = await reader.getVaultAllocation('0xTokenAddress');

// Get MEV protection config
const mev = await reader.getMevConfig('0xTokenAddress');

// Get available fees for a wallet
const fees = await reader.getAvailableFees('0xWallet', '0xToken');

// Check if token was deployed via Clawncher
const isClawnch = await reader.isClawnchToken('0xTokenAddress');

Claiming Fees

import { ClawncherClaimer } from '@clawnch/clawncher-sdk';

const claimer = new ClawncherClaimer({ wallet, publicClient, network: 'mainnet' });

// Collect LP rewards (triggers fee collection from positions)
await claimer.collectRewards('0xToken...');

// Claim fees from FeeLocker
await claimer.claimFees('0xWallet...', '0xToken...');

// Claim vault allocation
await claimer.claimVault('0xToken...');

// Claim everything at once
await claimer.claimAll('0xToken...', { claimVault: true });

// Batch claim across multiple tokens
const result = await claimer.claimBatch(tokens, feeOwner, {
  onProgress: (token, step) => console.log(`${token}: ${step}`),
});

Dry Run

const result = await deployer.deploy({
  ...options,
  dryRun: true,
});
// result.translatedConfig - the Clanker config (for inspection)
// result.estimatedGas - estimated gas
// result.estimatedCostEth - estimated cost in ETH

Error Handling

import { ClawnchDeployError, ClawnchErrorCode, isClawnchError } from '@clawnch/clawncher-sdk';

const result = await deployer.deploy(options);
if (isClawnchError(result.error)) {
  console.log(result.error.code);  // e.g. ClawnchErrorCode.INSUFFICIENT_FUNDS
  console.log(result.error.cause); // original error if any
}

Portfolio Tracking

import { ClawnchPortfolio } from '@clawnch/clawncher-sdk';

const portfolio = new ClawnchPortfolio({ publicClient, network: 'mainnet' });
const tokens = await portfolio.getTokensForWallet(wallet, knownTokens);
const claimable = await portfolio.getTotalClaimable(wallet, knownTokens);

Live Watching

import { ClawnchWatcher } from '@clawnch/clawncher-sdk';

const watcher = new ClawnchWatcher({ publicClient, network: 'mainnet' });
const unwatch = watcher.watchDeployments((event) => {
  console.log(`New: ${event.tokenSymbol} at ${event.tokenAddress}`);
});

Batch Fee Claiming

const result = await claimer.claimBatch(tokens, feeOwner, {
  onProgress: (token, step) => console.log(`${token}: ${step}`),
});

Token Swaps

Execute token swaps via 0x aggregation for best price across all Base DEXes. Swaps are routed through the Clawnch API — no API key needed.

import { ClawnchSwapper, NATIVE_TOKEN_ADDRESS } from '@clawnch/clawncher-sdk';
import { parseEther } from 'viem';

const swapper = new ClawnchSwapper({
  wallet,
  publicClient,
});

// Get indicative price (read-only, no commitment)
const price = await swapper.getPrice({
  sellToken: NATIVE_TOKEN_ADDRESS,  // ETH
  buyToken: '0xTokenAddress...',
  sellAmount: parseEther('0.01'),
});
console.log('You would receive:', price.buyAmount);
console.log('Liquidity:', price.liquidityAvailable);

// Get firm quote (market makers commit assets)
const quote = await swapper.getQuote({
  sellToken: NATIVE_TOKEN_ADDRESS,
  buyToken: '0xTokenAddress...',
  sellAmount: parseEther('0.01'),
});

// Full swap execution: quote → approve → send → wait
const result = await swapper.swap({
  sellToken: NATIVE_TOKEN_ADDRESS,
  buyToken: '0xTokenAddress...',
  sellAmount: parseEther('0.01'),
  slippageBps: 100,  // 1% (default)
});
console.log('Tx:', result.txHash);
console.log('Received:', result.buyAmount);

Swap Helpers

// Token balance (ETH or ERC20)
const balance = await swapper.getBalance(tokenAddress);

// Token metadata
const decimals = await swapper.getDecimals(tokenAddress);
const symbol = await swapper.getSymbol(tokenAddress);

// Allowance management
const allowance = await swapper.getAllowance(token, owner, spender);
await swapper.approveToken(token, spender);

// Format amount to human-readable
const formatted = await swapper.formatAmount(tokenAddress, rawAmount);

Swap Constants

import {
  NATIVE_TOKEN_ADDRESS,  // 0xEeee...eEEeE (0x representation of native ETH)
  BASE_WETH,             // 0x4200...0006
  BASE_CHAIN_ID,         // 8453
  ZEROX_API_BASE,        // https://api.0x.org
} from '@clawnch/clawncher-sdk';

Liquidity Management

Manage Uniswap V3 and V4 liquidity positions on Base.

import { ClawnchLiquidity } from '@clawnch/clawncher-sdk';

const liquidity = new ClawnchLiquidity({ wallet, publicClient });

V3 Positions (Full CRUD)

// List all positions for a wallet
const positions = await liquidity.v3GetPositionsForWallet('0xWallet...');

// Get single position
const pos = await liquidity.v3GetPosition(tokenId);
console.log(pos.liquidity, pos.unclaimedFees);

// Mint new position
const result = await liquidity.v3MintPosition({
  token0: '0xTokenA...',
  token1: '0xTokenB...',
  fee: 3000,
  tickLower: -887220,
  tickUpper: 887220,
  amount0Desired: parseEther('1'),
  amount1Desired: parseUnits('2000', 6),
});

// Add liquidity to existing position
await liquidity.v3AddLiquidity(tokenId, {
  amount0Desired: parseEther('0.5'),
  amount1Desired: parseUnits('1000', 6),
});

// Remove 50% of liquidity
await liquidity.v3RemoveLiquidity(tokenId, {
  percentageToRemove: 0.5,
});

// Remove 100% and burn NFT
await liquidity.v3RemoveLiquidity(tokenId, {
  percentageToRemove: 1.0,
  burnToken: true,
});

// Collect unclaimed fees
const fees = await liquidity.v3CollectFees(tokenId);

// Filter positions by token
const tokenPositions = await liquidity.getPositionsForToken('0xToken...');

V4 Pool Reading

// Read V4 pool state
const state = await liquidity.v4GetPoolState({
  currency0: '0xTokenA...',
  currency1: '0xTokenB...',
  fee: 3000,
  tickSpacing: 60,
  hooks: '0x0000000000000000000000000000000000000000',
});

// Read V4 position
const pos = await liquidity.v4GetPosition(tokenId);

// Execute V4 multicall (use with @uniswap/v4-sdk calldata)
const { txHash, receipt } = await liquidity.v4ExecuteMulticall(calldata, ethValue);

Uniswap Addresses

import {
  getUniswapV4Addresses,
  getUniswapV3Addresses,
  getCommonAddresses,
} from '@clawnch/clawncher-sdk';

const v4 = getUniswapV4Addresses('mainnet');
// v4.poolManager, v4.positionManager, v4.stateView, v4.quoter, v4.permit2, ...

const v3 = getUniswapV3Addresses('mainnet');
// v3.factory, v3.nonfungiblePositionManager, v3.swapRouter, v3.quoterV2

const common = getCommonAddresses('mainnet');
// common.weth, common.usdc

API Client (Optional)

For API-based operations (tokens list, launches, analytics):

import { ClawnchClient } from '@clawnch/clawncher-sdk';

const client = new ClawnchClient();

// Get all tokens from API
const tokens = await client.getTokens();

// Get launch history
const launches = await client.getLaunches({ limit: 10 });

// Get market stats
const stats = await client.getStats();

Contract Addresses

import { getAddresses } from '@clawnch/clawncher-sdk';

const addresses = getAddresses('mainnet'); // or 'sepolia'
console.log(addresses.clawnch.factory);
console.log(addresses.clawnch.devBuy);

Base Mainnet (v3 via Clanker)

| Contract | Address | |----------|---------| | Factory | 0xE85A59c628F7d27878ACeB4bf3b35733630083a9 | | Hook | 0x6F5e57a4e81E93b8235710E3aA14E8c1d3d3bcb8 | | LP Locker | 0x63D2DfEA64b3433F4071A98665bcD7Ca14d93496 | | FeeLocker | 0x42A95190B4088C88Dd904d930c79deC1158bF09D | | Vault | 0xcC80d1226F899a78fC2E459a1500A13C373CE0A5 | | DevBuy | 0x97fd42fcc8c4E2A5a45d0e28E14EC60FF7c10D9C |

Base Sepolia (v3 via Clanker)

| Contract | Address | |----------|---------| | Factory | 0xE85A59c628F7d27878ACeB4bf3b35733630083a9 | | Hook | 0x6F5e57a4e81E93b8235710E3aA14E8c1d3d3bcb8 | | LP Locker | 0x63D2DfEA64b3433F4071A98665bcD7Ca14d93496 | | FeeLocker | 0x42A95190B4088C88Dd904d930c79deC1158bF09D | | Vault | 0xcC80d1226F899a78fC2E459a1500A13C373CE0A5 | | DevBuy | 0x97fd42fcc8c4E2A5a45d0e28E14EC60FF7c10D9C |

Types

import type {
  // Deployer types
  DeployOptions,
  DeployResult,
  VaultConfig,
  DevBuyConfig,
  RewardRecipient,
  FeePreference,
  NetworkName,
  // Reader types
  TokenDetails,
  VaultAllocation,
  MevConfigInfo,
  TokenRewardInfo,
  WalletFeeInfo,
  // Error types
  ClawnchErrorCode,
  ClawnchDeployError,
  // Dry run
  DryRunResult,
  // Batch claiming
  BatchClaimResult,
  // Portfolio
  PortfolioToken,
  // Watcher
  NewTokenEvent,
  // Swap types
  SwapperConfig,
  SwapParams,
  SwapPriceResult,
  SwapQuoteResult,
  SwapResult,
  SwapTransaction,
  // Liquidity types
  LiquidityConfig,
  V4PoolKey,
  V4PoolState,
  V3MintParams,
  V3AddLiquidityParams,
  V3RemoveLiquidityParams,
  PositionInfo,
  MintResult,
  ModifyLiquidityResult,
  CollectFeesResult,
  // Uniswap address types
  UniswapV4Addresses,
  UniswapV3Addresses,
  CommonAddresses,
  // Verified agent launch types
  ClawnchApiDeployer,
  ApiDeployerConfig,
  RegisterConfig,
  RegisterRequest,
  VerifyResponse,
  AgentStatus,
  ApiDeployRequest,
  ApiDeployResponse,
  ApprovalResult,
  CaptchaChallenge,
  CaptchaSolution,
} from '@clawnch/clawncher-sdk';

Verified Agent Launches

Deploy tokens via the Clawnch API to receive a verified badge. The ClawnchApiDeployer handles registration, captcha solving, and deployment.

Note: Server-side API endpoints are pending deployment. The SDK client is ready.

import { ClawnchApiDeployer } from '@clawnch/clawncher-sdk';

// One-time registration (returns API key)
const { apiKey } = await ClawnchApiDeployer.register(
  { wallet, publicClient },
  { name: 'MyAgent', wallet: account.address, description: 'AI trading agent' }
);

// Create deployer with API key
const apiDeployer = new ClawnchApiDeployer({
  apiKey,
  wallet,
  publicClient,
});

// One-time $CLAWNCH approval
await apiDeployer.approveClawnch();

// Deploy a verified token
const result = await apiDeployer.deploy({
  name: 'My Token',
  symbol: 'MYTKN',
  image: 'https://example.com/logo.png',
});
console.log('Token:', result.tokenAddress);

Methods:

| Method | Description | |--------|-------------| | ClawnchApiDeployer.register(config, request) | Register agent, receive API key | | getStatus() | Agent verification status and balance | | approveClawnch(spender?) | One-time $CLAWNCH max approval | | getClawnchAllowance(spender) | Check $CLAWNCH allowance | | getClawnchBalance() | Check $CLAWNCH balance | | deploy(request) | Full verified deploy flow |

Links

• Website: https://clawn.ch/er
• CLI: npm install -g clawncher
• Documentation: https://clawn.ch/er/docs

License

MIT