# Liquid Protocol

> Token launcher on Base (chain 8453) with Uniswap V4 — deploy ERC-20 tokens with locked LP, MEV protection, and fee splits in a single transaction.

Website: https://app.liquidprotocol.org
Docs: https://liquidprotocol.org
NPM: https://www.npmjs.com/package/liquid-sdk
GitHub: https://github.com/Liquid-Protocol-Ops/SDK
Contracts: https://github.com/Liquid-Protocol-Ops/liquid-protocol-v0
Twitter: https://x.com/liquidprotocol

## SDK — liquid-sdk

TypeScript SDK. Zero API keys, one dependency (viem). Fully agentic — works from scripts, backends, and AI agents.

### Install

```
npm install liquid-sdk viem
```

### Quick Start

```typescript
import { createPublicClient, createWalletClient, http } from "viem";
import { base } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";
import { LiquidSDK } from "liquid-sdk";

const publicClient = createPublicClient({ chain: base, transport: http() });
const account = privateKeyToAccount("0x...");
const walletClient = createWalletClient({ account, chain: base, transport: http() });
const sdk = new LiquidSDK({ publicClient, walletClient });

const result = await sdk.deployToken({ name: "My Token", symbol: "MTK" });
console.log(result.tokenAddress);
```

Read-only usage (no wallet needed):

```typescript
const sdk = new LiquidSDK({ publicClient });
const info = await sdk.getTokenInfo("0x...");
```

## API Methods

### Token Deployment
- `sdk.deployToken(params)` — Deploy ERC-20 + Uniswap V4 pool. Params: name (required), symbol (required), image, metadata, context, devBuy, hook, tickSpacing, poolData, rewardRecipients, rewardBps, extensions
- `sdk.buildDevBuyExtension(devBuy)` — Build extension config for buying tokens at launch

### Fee Management
- `sdk.getAvailableFees(feeOwner, tokenAddress)` — Total unlocked fees (bigint)
- `sdk.getFeesToClaim(feeOwner, tokenAddress)` — Claimable fees right now (bigint)
- `sdk.claimFees(feeOwner, tokenAddress)` — Claim fees (returns txHash)

### LP Reward Management
- `sdk.getTokenRewards(tokenAddress)` — Reward config (recipients, bps, admins, poolKey)
- `sdk.collectRewards(tokenAddress)` — Collect + unlock LP (returns txHash)
- `sdk.collectRewardsWithoutUnlock(tokenAddress)` — Collect fees only (returns txHash)
- `sdk.updateRewardRecipient(tokenAddress, index, newRecipient)` — Change recipient (returns txHash)

### Vault (Token Lockup & Vesting)
- `sdk.getVaultAllocation(tokenAddress)` — Vault state (total, claimed, lockup/vesting times, admin)
- `sdk.getVaultClaimable(tokenAddress)` — Tokens available to claim now (bigint)
- `sdk.claimVault(tokenAddress)` — Claim vested tokens (returns txHash)

### Airdrop
- `sdk.getAirdropInfo(tokenAddress)` — Airdrop state (merkle root, supply, claimed, times)
- `sdk.getAirdropClaimable(tokenAddress, recipient, amount)` — Claimable for recipient (bigint)
- `sdk.claimAirdrop(tokenAddress, recipient, amount, proof)` — Claim airdrop (returns txHash)

### Token Info & Discovery
- `sdk.getTokenInfo(tokenAddress)` — Name, symbol, decimals, totalSupply, deployment addresses
- `sdk.getDeploymentInfo(tokenAddress)` — Token, hook, locker, extensions addresses
- `sdk.getTokens(options?)` — Query all deployed tokens with optional deployer filter and block range pagination
- `sdk.getTokenEvent(tokenAddress)` — Look up single token's on-chain event data by address
- `sdk.getDeployedTokens(deployer, fromBlock?, toBlock?)` — Convenience wrapper for getTokens({ deployer })

### Token Metadata Updates
- `sdk.updateImage(tokenAddress, newImageUrl)` — Update token image (admin only)
- `sdk.updateMetadata(tokenAddress, newMetadata)` — Update token metadata (admin only)

### Pool Reads
- `sdk.getPoolConfig(poolId)` — Dynamic fee configuration
- `sdk.getPoolFeeState(poolId)` — Current fee state
- `sdk.getPoolCreationTimestamp(poolId)` — Pool creation time
- `sdk.isLiquidToken0(poolId)` — Token sort order in pool

### Sniper Auction (MEV)
- `sdk.getAuctionState(poolId)` — Current auction state (block, round, gasPeg, fee)
- `sdk.getAuctionFeeConfig(poolId)` — Fee parameters (starting, ending, decay)
- `sdk.getAuctionDecayStartTime(poolId)` — When fee decay started
- `sdk.getAuctionMaxRounds()` — Max auction rounds
- `sdk.getAuctionGasPriceForBid(gasPeg, bidAmount)` — Calculate gas price for bid

### MEV Protection
- `sdk.getMevBlockDelay()` — Configured block delay
- `sdk.getPoolUnlockTime(poolId)` — When MEV lock expires (unix timestamp)

### Factory & Allowlist
- `sdk.isFactoryDeprecated()` — Is factory still active
- `sdk.isLockerEnabled(locker, hook)` — Is locker approved for hook
- `sdk.isExtensionEnabled(extension)` — Is extension on allowlist

### Context & Metadata Helpers
- `buildContext({ interface?, platform?, messageId?, id? })` — Build JSON context string
- `buildMetadata({ description?, socialMediaUrls?, auditUrls? })` — Build JSON metadata string
- `parseContext(contextString)` — Parse context JSON to typed object
- `parseMetadata(metadataString)` — Parse metadata JSON to typed object

## Utility Functions

- `encodeStaticFeePoolData(liquidFeeBps, pairedFeeBps)` — Encode static fee config
- `encodeDynamicFeePoolData(config)` — Encode dynamic fee config
- `encodeSniperAuctionData(config)` — Encode MEV auction config
- `createPositions(startingCapETH, tranches)` — Build position arrays from ETH market caps
- `createPositionsUSD(startingCapUSD, ethPrice, tranches)` — Build from USD market caps
- `createDefaultPositions(startingCapUSD, ethPrice)` — Default 3-tranche (40%@$500K, 50%@$10M, 10%@$1B)
- `describePositions(positions, ethPrice?)` — Human-readable position descriptions
- `getTickFromMarketCapETH(capETH)` / `getTickFromMarketCapUSD(capUSD, ethPrice)` — Market cap to tick
- `marketCapFromTickETH(tick)` / `marketCapFromTickUSD(tick, ethPrice)` — Tick to market cap

## Default Deployment Values

| Field | Default |
|-------|---------|
| hook | Static fee V2 (1% buy + 1% sell) |
| tickSpacing | 200 |
| tickIfToken0IsLiquid | -230400 (~10 ETH market cap) |
| positions | 5-position Liquid layout: 10%/50%/15%/20%/5% |
| mevModule | Sniper Auction V2 (80% to 40% over 20s) |
| rewardRecipients | [deployer] at 100% |
| context | {"interface":"SDK"} |
| totalSupply | 100,000,000,000 (100B, 18 decimals) |

## Contract Addresses (Base Mainnet, chain 8453)

- Liquid (Factory) (Core): 0x04F1a284168743759BE6554f607a10CEBdB77760
- LiquidFeeLocker (Core): 0xF7d3BE3FC0de76fA5550C29A8F6fa53667B876FF
- LiquidPoolExtensionAllowlist (Core): 0xb614167d79aDBaA9BA35d05fE1d5542d7316Ccaa
- LiquidHookDynamicFeeV2 (Hooks): 0x80E2F7dC8C2C880BbC4BDF80A5Fb0eB8B1DB68CC
- LiquidHookStaticFeeV2 (Hooks): 0x9811f10Cd549c754Fa9E5785989c422A762c28cc
- LiquidLpLockerFeeConversion (LP Lockers): 0x77247fCD1d5e34A3703AcA898A591Dc7422435f3
- LiquidAirdropV2 (Extensions): 0x1423974d48f525462f1c087cBFdCC20BDBc33CdD
- LiquidVault (Extensions): 0xdFCCC93257c20519A9005A2281CFBdF84836d50E
- LiquidUniv4EthDevBuy (Extensions): 0x5934097864dC487D21A7B4e4EEe201A39ceF728D
- LiquidUniv3EthDevBuy (Extensions): 0x376028cfb6b9A120E24Aa14c3FAc4205179c0025
- LiquidPresaleEthToCreator (Extensions): 0x3bca63EcB49d5f917092d10fA879Fdb422740163
- LiquidPresaleAllowlist (Extensions): 0xCBb4ccC4B94E23233c14759f4F9629F7dD01f10B
- LiquidSniperAuctionV2 (MEV Modules): 0x187e8627c02c58F31831953C1268e157d3BfCefd
- LiquidMevDescendingFees (MEV Modules): 0x8D6B080e48756A99F3893491D556B5d6907b6910
- LiquidSniperUtilV2 (MEV Modules): 0x2B6cd5Be183c388Dd0074d53c52317df1414cd9f
- Uniswap V4 Pool Manager (External): 0x498581fF718922c3f8e6A244956aF099B2652b2b
- WETH (External): 0x4200000000000000000000000000000000000006
- Universal Router (External): 0x6fF5693b99212Da76ad316178A184AB56D299b43
- Permit2 (External): 0x000000000022D473030F116dDEE9F6B43aC78BA3

## Indexer API

Base URL: configurable (production deployment on Railway).

All endpoints except /health require the `x-api-key` header.

### Endpoints

- `GET /health` — Service status. No auth required.
- `POST /index` — Index a token deployment by transaction hash. Body: `{ "txHash": "0x..." }`. Requires x-api-key.
- `GET /fees/:tokenAddress?owner=0x...` — Fee balances for a token/owner pair. Requires x-api-key.
- `GET /wallet/:address/fees` — Aggregated fee balances across all tokens for a wallet. Requires x-api-key.
- `GET /rewards/:tokenAddress` — Reward configuration for a token. Requires x-api-key.
- `POST /tx/:tokenAddress` — Build an unsigned transaction. Body: `{ "action": "claim-fees" | "collect-rewards" | "update-image" | "update-metadata", ... }`. Requires x-api-key.

## Website API Routes

Base URL: https://app.liquidprotocol.org

These are public, no API key required.

- `GET /api/tokens/{address}/info` — Token + deployment info (name, symbol, decimals, supply, hook, locker, extensions)
- `GET /api/tokens/{address}/fees` — Fee data for a token
- `GET /api/tokens/{address}/rewards` — Reward configuration and state

## Links

- NPM: https://www.npmjs.com/package/liquid-sdk
- GitHub: https://github.com/Liquid-Protocol-Ops/SDK
- Twitter: https://x.com/liquidprotocol