@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 { ClawnchApiDeployer } from '@clawnch/clawncher-sdk';
import { createWalletClient, createPublicClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';

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

const deployer = new ClawnchApiDeployer({
  apiKey: 'your-api-key',
  wallet,
  publicClient,
});

const result = await deployer.deploy({
  name: 'My Token',
  symbol: 'MYTKN',
});
console.log('Token deployed:', result.tokenAddress);

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 the deployment infrastructure. 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 deployment 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';

Uniswap V4 Trading API

Execute swaps via the Uniswap Trading API with automatic Permit2 approval handling. Supports all 15 Uniswap chains.

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

const trading = new UniswapTradingApi({
  wallet,
  publicClient,
  chainId: 8453,
  apiKey: process.env.UNISWAP_API_KEY,
  slippageBps: 50, // 0.5%
});

// Full swap: check_approval → quote → swap (handles Permit2 automatically)
const result = await trading.swap({
  tokenIn: NATIVE_TOKEN_ADDRESS,
  tokenOut: '0xTokenAddress...',
  amount: parseEther('0.01'),
});
console.log('Tx:', result.txHash);

// Quote only (no execution)
const quote = await trading.getQuote({
  tokenIn: NATIVE_TOKEN_ADDRESS,
  tokenOut: '0xTokenAddress...',
  amount: parseEther('0.01'),
});
console.log('Output:', quote.quoteAmount, 'Impact:', quote.priceImpact);

// Generate Uniswap app deep link
const link = trading.getSwapDeepLink({
  tokenIn: NATIVE_TOKEN_ADDRESS,
  tokenOut: '0xTokenAddress...',
  amount: parseEther('0.1'),
});

The Trading API uses a 3-step flow: POST /check_approval → POST /quote → POST /swap. The swap() method handles all three steps including Permit2 approvals. Sign up for an API key at hub.uniswap.org.

On-Chain V4 Quoter

Simulate swaps directly against V4 pools without an API key. Includes Clawnch-native pool discovery via the LP locker contract.

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

const quoter = new UniswapQuoter({
  publicClient,
  chainId: 8453,
});

// One-call quote for any Clawnch token (auto-discovers pool key from LP locker)
const quote = await quoter.quoteClawnchToken(
  '0xTokenAddress...',
  parseEther('0.01'),
  'buy', // 'buy' = ETH→Token, 'sell' = Token→ETH
);
console.log('Output:', quote.quotedAmount);
console.log('Impact:', quote.priceImpact);
console.log('Hook:', quote.poolKey.hooks); // correct MEV hook, not zero address

// Build pool key from LP locker (includes hook address, fee, tick spacing)
const poolKey = await quoter.buildPoolKeyFromToken('0xTokenAddress...');

// Read pool state (sqrtPriceX96, tick, liquidity)
const state = await quoter.getPoolState(poolKey);

// Manual quote with explicit pool key
const manualQuote = await quoter.quoteExactInput({
  poolKey,
  zeroForOne: true,
  amount: parseEther('0.01'),
});

// Estimate price impact without a full quote
const impact = await quoter.estimatePriceImpact(poolKey, parseEther('1'));

buildPoolKeyFromToken() reads the LP locker via ClawnchReader.getTokenRewards() to auto-discover the correct pool key — including the MEV hook address. This is critical because defaulting the hook to the zero address targets the wrong pool for Clawnch tokens.

Permit2 Client

Manage token approvals for Uniswap V4 via the Permit2 contract. Supports both AllowanceTransfer (PositionManager) and SignatureTransfer (UniversalRouter).

import { Permit2Client, PERMIT2_ADDRESS } from '@clawnch/clawncher-sdk';

const permit2 = new Permit2Client({
  wallet,
  publicClient,
  chainId: 8453,
});

// Full approval flow: ERC20→Permit2 + Permit2→spender
const { approvalTxHash, permitTxHash } = await permit2.ensurePermit2Allowance(
  tokenAddress,
  spenderAddress, // e.g. UniversalRouter
  amount,
);

// Two-token approval for LP operations
await permit2.ensurePermit2AllowancePair(
  token0, token1, positionManagerAddress, amount0, amount1,
);

// Check allowance state
const allowance = await permit2.getAllowance(tokenAddress, spenderAddress);
console.log('Amount:', allowance.amount, 'Expires:', allowance.expiration);

// Emergency lockdown — revoke all access
await permit2.lockdown([
  { token: tokenA, spender: routerAddress },
  { token: tokenB, spender: routerAddress },
]);

// Sign off-chain permits (AllowanceTransfer)
const signed = await permit2.signPermitSingle({
  token: tokenAddress,
  spender: routerAddress,
});

// Sign off-chain permits (SignatureTransfer — bitmap nonces)
const nonce = await permit2.findUnusedNonce(0n);
const transfer = await permit2.signPermitTransferFrom({
  token: tokenAddress,
  amount: parseEther('1'),
  spender: routerAddress,
  nonce,
});

Permit2 is deployed at 0x000000000022D473030F116dDEE9F6B43aC78BA3 on all chains.

Multi-Chain Uniswap Registry

Address registry for all 15 Uniswap-supported chains.

import {
  getUniswapChain,
  getAllUniswapChains,
  getTradingApiChains,
  getV4Chains,
  chainIdFromSlug,
  FEE_TIERS,
} from '@clawnch/clawncher-sdk';

// Get config for a specific chain
const base = getUniswapChain(8453);
console.log(base.v4UniversalRouter, base.weth, base.permit2);

// All chains with Trading API support
const tradingChains = getTradingApiChains(); // 15 chains

// All chains with V4 deployed
const v4Chains = getV4Chains();

// Resolve slug to chain ID
const chainId = chainIdFromSlug('arbitrum'); // 42161

// Fee tiers with tick spacing
FEE_TIERS.forEach(t => console.log(t.label, t.fee, t.tickSpacing));

Supported chains: Ethereum, Base, Arbitrum, Optimism, Polygon, BNB Chain, Unichain, Avalanche, Celo, Blast, Zora, World Chain, Soneium, zkSync, Monad.

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)

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

Base Sepolia (v3)

| 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,
  // Uniswap Trading API types
  UniswapTradingConfig,
  TradingSwapParams,
  TradingQuote,
  TradingSwapResult,
  ApprovalCheckResult,
  // Uniswap Quoter types
  QuoterConfig,
  PoolKey,
  QuoteParams,
  QuoteResult,
  PoolState,
  // Permit2 types
  Permit2Config,
  Permit2Allowance,
  PermitSingleParams,
  PermitBatchParams,
  SignedPermitSingle,
  SignedPermitBatch,
  // Multi-chain registry types
  UniswapChainConfig,
  FeeTier,
  // 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 |

Wayfinder Integration (Cross-chain DeFi)

Access cross-chain swaps, multi-chain balances, and DeFi strategies via Wayfinder Paths.

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

const wf = new WayfinderClient({ apiKey: 'wk_...' });

// Tier 1 (REST - no Python required):
const quote = await wf.quoteSwap({
  fromToken: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC Ethereum
  toToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',   // USDC Base
  fromChain: 1, toChain: 8453,
  fromWallet: '0x...', amount: '5000000',
});
console.log(quote.bestQuote?.provider, quote.bestQuote?.outputAmountUsd);

const balances = await wf.getBalances('0x...');
const token = await wf.resolveToken('USDC', 8453);

// Tier 2 (requires Python 3.12+ and wayfinder-paths):
const status = await wf.checkPython();
if (status.wayfinderInstalled) {
  const result = await wf.executeSwap({
    kind: 'swap', walletLabel: 'main',
    amount: '5', fromToken: 'usd-coin', toToken: 'ethereum',
  });
  await wf.runStrategy({ strategy: 'basis_trading_strategy', action: 'status' });
}

REST Methods (always available)

| Method | Description | |--------|-------------| | quoteSwap(params) | Cross-chain swap quotes via BRAP aggregator | | resolveToken(query, chainId?) | Token details by name/symbol/address | | searchTokens(query, chain) | Fuzzy token search | | getGasToken(chain) | Gas token for a chain | | getBalances(address) | Multi-chain enriched balances | | getWalletActivity(address) | Transaction history | | getPools(chainId?, protocol?) | DeFi pool data | | getHyperliquidFunding(coin) | Funding rate history | | getHyperliquidCandles(coin, interval) | OHLCV data | | getHyperLendMarkets() | HyperLend stable markets |

CLI Bridge Methods (requires Python + wayfinder-paths)

| Method | Description | |--------|-------------| | checkPython() | Check Python/wayfinder-paths availability | | executeSwap(params) | Execute swap with local signing | | runStrategy(params) | Run strategy action (status/deposit/update/exit) | | listStrategies() | List available strategies | | getStrategyStatus(name) | Get strategy status |

Supported chains: Ethereum (1), Base (8453), Arbitrum (42161), Polygon (137), BSC (56), Avalanche (43114), HyperEVM (999).

Hummingbot Market Making

Operate Hummingbot programmatically — 101 methods covering all 14 API routers (accounts, connectors, trading, executors, controllers, bots, scripts, market data, portfolio, gateway, rate oracle, backtesting, history, Docker).

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

const hb = new HummingbotClient({
  apiUrl: 'http://localhost:8000',  // or HUMMINGBOT_API_URL
  username: 'admin',                // or HUMMINGBOT_USERNAME
  password: 'admin',                // or HUMMINGBOT_PASSWORD
});

// Health check (unauthenticated)
const health = await hb.checkHealth();

// Portfolio across all connected exchanges
const portfolio = await hb.getPortfolioOverview();

// Place an order
await hb.placeOrder({
  connectorName: 'binance',
  tradingPair: 'ETH-USDT',
  tradeType: 'BUY',
  amount: '0.1',
  orderType: 'MARKET',
});

// Market data
const candles = await hb.getCandles('binance', 'ETH-USDT', '1h', 7);
const book = await hb.getOrderBook('binance', 'ETH-USDT');
const prices = await hb.getPrices('binance', 'ETH-USDT');

// Create and deploy a bot with a controller config
await hb.upsertControllerConfig({ id: 'mm_eth', controller_type: 'market_making', /* ... */ });
await hb.deployBot({ controllers: ['mm_eth'], connectorName: 'binance' });

// Executor management
await hb.createExecutor({
  executorType: 'grid_executor',
  connectorName: 'binance',
  tradingPair: 'ETH-USDT',
  side: 1,
  startPrice: 3000,
  endPrice: 3500,
  totalAmountQuote: 1000,
  levels: 10,
});

// Gateway (DEX / on-chain)
const chains = await hb.listGatewayChains();
await hb.executeGatewayAmmTrade({ chain: 'ethereum', network: 'mainnet', /* ... */ });
const pools = await hb.listCLMMPools({ chain: 'ethereum', network: 'mainnet', connector: 'uniswap' });

// Backtesting
const result = await hb.runBacktest({ startTime: 1700000000, endTime: 1700100000, config: { /* ... */ } });

// Strategy templates (local, no API call)
const templates = hb.getStrategyTemplates();
const built = hb.buildFromTemplate('pure_market_making', { connector: 'binance', tradingPair: 'ETH-USDT' });

Strategy Templates

9 built-in templates — 4 for the Clawnch token lifecycle, 5 general-purpose:

| Template | Purpose | |----------|---------| | clawnch_initial_liquidity | Tight spreads for freshly launched tokens | | clawnch_post_launch_mm | Wider spreads with depth as volume grows | | clawnch_fee_optimization | Uniswap V4 hook fee optimization | | clawnch_accumulation | DCA position building over time | | pure_market_making | Standard bid/ask market making | | avellaneda_market_making | Inventory-aware spread adjustment | | grid_trading | Grid orders across a price range | | dca_buying | Dollar-cost averaging | | twap_execution | Time-weighted average price execution |

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | HUMMINGBOT_API_URL | http://localhost:8000 | Hummingbot API server URL | | HUMMINGBOT_USERNAME | admin | HTTP Basic Auth username | | HUMMINGBOT_PASSWORD | admin | HTTP Basic Auth password | | HUMMINGBOT_TIMEOUT | 30000 | Request timeout (ms) | | HUMMINGBOT_MAX_RETRIES | 3 | Retry count for 5xx/network errors | | HUMMINGBOT_RETRY_DELAY | 1000 | Base retry delay (ms) |

Related Packages

• @clawnch/clawtomaton — Autonomous AI agents built on this SDK. Agents generate wallets, burn $CLAWNCH to activate, deploy tokens, and sustain themselves through LP fees.
• clawncher — CLI tool for deploying and managing tokens
• clawnch-mcp-server — MCP server for Claude, Cursor, OpenCode

Links

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

License

MIT