liquid-sdk 1.7.3 → 1.7.5

package/README.md

@@ -2,34 +2,79 @@
 
 TypeScript SDK for the Liquid Protocol token launcher on Base. Deploy tokens, manage pools, and claim fees using [viem](https://viem.sh).
 
+## Agent Skills
+
+The SDK ships with **agent skill files** — self-contained markdown guides that AI agents can load into their context to autonomously interact with Liquid Protocol on Base.
+
+| Skill | File | What it teaches |
+|-------|------|-----------------|
+| **SDK Overview** | `skills/sdk-overview.md` | Full capabilities, data schemas (metadata, context, rewards, vault, airdrop), default config — load this first |
+| **Deploy Token** | `skills/deploy-token.md` | Deployment workflows — minimal deploy, dev buy, custom fees, custom positions, reward splits |
+| **Bid in Auction** | `skills/bid-in-auction.md` | MEV sniper auction — WETH handling, gas price encoding, block timing, automated sniper example |
+| **Index Tokens** | `skills/index-tokens.md` | Token discovery — bulk queries, single lookup, pagination, real-time monitoring |
+
+### Using Skills with Your Agent
+
+```python
+# Python — load a skill into your agent's context
+with open("node_modules/liquid-sdk/skills/deploy-token.md") as f:
+    agent.system_prompt += f.read()
+```
+
+```typescript
+// TypeScript — read skill for an MCP server or agent framework
+import { readFileSync } from "fs";
+const skill = readFileSync("node_modules/liquid-sdk/skills/bid-in-auction.md", "utf-8");
+```
+
+For Claude Code, reference skills in your `CLAUDE.md`:
+```
+For token deployment, follow the instructions in node_modules/liquid-sdk/skills/deploy-token.md
+```
+
+### Additional Agent Docs
+
+| File | Purpose |
+|------|---------|
+| `AGENT_README.md` | Complete API reference with every method, type, and default (700+ lines) |
+| `llms.txt` | Compact summary for LLM context windows |
+| `CLAUDE.md` | Agent guide with architecture, defaults, and invariants |
+
 ## Installation
 
 ```bash
-npm install liquid-protocol-sdk viem
+npm install liquid-sdk viem
 ```
 
+> **Defaults**: Static 1% fee (both buy and sell), 5-position Liquid layout, Sniper Auction MEV (80%→40% over 20s, 5 rounds), tick spacing 200, starting tick -230400 (~10 ETH market cap). All fees converted to ETH before distribution.
+
+### Default Liquidity Positions
+
+| # | Supply | Tick Range | Market Cap Range (@$2,000/ETH) |
+|---|--------|-----------|-------------------------------|
+| 1 | 10% | -230,400 → -216,000 | ~$20K → ~$83K |
+| 2 | 50% | -216,000 → -155,000 | ~$83K → ~$37M |
+| 3 | 15% | -202,000 → -155,000 | ~$338K → ~$37M |
+| 4 | 20% | -155,000 → -120,000 | ~$37M → ~$1.2B |
+| 5 | 5% | -141,000 → -120,000 | ~$151M → ~$1.2B |
+
 ## Quick Start
 
 ```typescript
-import { createPublicClient, createWalletClient, http } from "viem";
+import { createWalletClient, http } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { base } from "viem/chains";
-import { LiquidSDK } from "liquid-protocol-sdk";
+import { LiquidSDK } from "liquid-sdk";
 
 const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
 
-const publicClient = createPublicClient({
-  chain: base,
-  transport: http(),
-});
-
 const walletClient = createWalletClient({
   account,
   chain: base,
   transport: http(),
 });
 
-const liquid = new LiquidSDK({ publicClient, walletClient });
+const liquid = new LiquidSDK({ walletClient });
 ```
 
 ## Deploy a Token
@@ -47,110 +92,126 @@ console.log("Pool ID:", result.event.poolId);
 console.log("Tx:", result.txHash);
 ```
 
-### Deploy with Custom Configuration
+### Deploy with Custom Market Cap Positions
 
 ```typescript
-import { ADDRESSES, EXTERNAL } from "liquid-protocol-sdk";
+import { createDefaultPositions, createPositionsUSD } from "liquid-sdk";
+
+// Use default 3-tranche split ($500K / $10M / $1B) at current ETH price
+const positions = createDefaultPositions(20_000, 2070); // $20K start, $2070/ETH
 
 const result = await liquid.deployToken({
-  name: "Custom Token",
-  symbol: "CTK",
-
-  // Pool config
-  hook: ADDRESSES.HOOK_STATIC_FEE_V2, // use static fee hook
-  pairedToken: EXTERNAL.WETH,
-  tickSpacing: 60,
-  tickIfToken0IsLiquid: -198720,
-
-  // LP rewards: split 70/30 between creator and platform
-  rewardAdmins: [creatorAddress, platformAddress],
-  rewardRecipients: [creatorAddress, platformAddress],
-  rewardBps: [7000, 3000],
-
-  // Full-range single position
-  tickLower: [-887220],
-  tickUpper: [887220],
-  positionBps: [10000],
-
-  // MEV protection
-  mevModule: ADDRESSES.MEV_BLOCK_DELAY,
+  name: "My Token",
+  symbol: "MTK",
+  ...positions, // tickLower, tickUpper, positionBps, tickIfToken0IsLiquid
 });
+
+// Or define fully custom tranches
+const custom = createPositionsUSD(50_000, 2070, [
+  { upperMarketCapUSD: 1_000_000, supplyPct: 30 },
+  { upperMarketCapUSD: 50_000_000, supplyPct: 50 },
+  { upperMarketCapUSD: 500_000_000, supplyPct: 20 },
+]);
 ```
 
-## Read Token Info
+### Deploy with Custom Fees
 
 ```typescript
-// Get ERC20 info + deployment details
-const info = await liquid.getTokenInfo(tokenAddress);
-console.log(info.name, info.symbol, info.decimals);
-console.log("Hook:", info.deployment.hook);
-console.log("Locker:", info.deployment.locker);
+import { ADDRESSES, encodeStaticFeePoolData, encodeDynamicFeePoolData } from "liquid-sdk";
 
-// Get deployment info only
-const deployment = await liquid.getDeploymentInfo(tokenAddress);
-```
-
-## Pool Information
+// Static 2% fee
+const result = await liquid.deployToken({
+  name: "Custom Fee Token",
+  symbol: "CFT",
+  poolData: encodeStaticFeePoolData(200, 200), // 2% both directions
+});
 
-```typescript
-// Get pool fee configuration (dynamic fee hook)
-const config = await liquid.getPoolConfig(poolId);
-console.log("Base fee:", config.baseFee);
-console.log("Max LP fee:", config.maxLpFee);
+// Dynamic fee (1%-5% range)
+const result2 = await liquid.deployToken({
+  name: "Dynamic Token",
+  symbol: "DYN",
+  hook: ADDRESSES.HOOK_DYNAMIC_FEE_V2,
+  poolData: encodeDynamicFeePoolData({
+    baseFeeBps: 100,
+    maxFeeBps: 500,
+    referenceTickFilterPeriod: 30,
+    resetPeriod: 120,
+    resetTickFilter: 200,
+    feeControlNumerator: 500000000n,
+    decayFilterBps: 7500,
+  }),
+});
+```
 
-// Get current fee state
-const feeState = await liquid.getPoolFeeState(poolId);
-console.log("Reference tick:", feeState.referenceTick);
-console.log("Last swap:", feeState.lastSwapTimestamp);
+## Sniper Auction (MEV Bidding)
 
-// Check pool creation time
-const created = await liquid.getPoolCreationTimestamp(poolId);
+Bid for early access to newly launched tokens. The SDK handles WETH wrapping, approvals, gas price encoding, and timing automatically.
 
-// Check token ordering
-const isToken0 = await liquid.isLiquidToken0(poolId);
+```typescript
+import { LiquidSDK, EXTERNAL } from "liquid-sdk";
+
+// 1. Get auction state & pool key
+const auction = await liquid.getAuctionState(poolId);
+const rewards = await liquid.getTokenRewards(tokenAddress);
+const zeroForOne = rewards.poolKey.currency0.toLowerCase() === EXTERNAL.WETH.toLowerCase();
+
+// 2. Calculate gas price for your bid
+const gasPrice = await liquid.getAuctionGasPriceForBid(auction.gasPeg, parseEther("0.001"));
+
+// 3. Wait for auction block, then fire
+const result = await liquid.bidInAuction({
+  poolKey: rewards.poolKey,
+  zeroForOne,
+  amountIn: parseEther("0.001"),     // WETH to swap (auto-wrapped)
+  amountOutMinimum: 0n,
+  round: auction.round,
+  bidAmount: parseEther("0.0005"),   // ETH bid (msg.value)
+}, gasPrice);
 ```
 
-## Claim Fees
+## Token Discovery
 
 ```typescript
-// Check available fees
-const available = await liquid.getAvailableFees(ownerAddress);
-const claimable = await liquid.getFeesToClaim(ownerAddress);
+// Get all tokens
+const allTokens = await liquid.getTokens();
 
-console.log("Available:", available);
-console.log("Claimable:", claimable);
+// Get tokens by deployer
+const myTokens = await liquid.getTokens({ deployer: myAddress });
 
-// Claim fees (defaults to WETH)
-const txHash = await liquid.claimFees(ownerAddress);
+// Look up a single token (fast, indexed)
+const token = await liquid.getTokenEvent(tokenAddress);
 
-// Optional: override the fee token explicitly
-const tokenClaimable = await liquid.getFeesToClaim(ownerAddress, tokenAddress);
+// Paginate with block ranges
+const page = await liquid.getTokens({ fromBlock: 20000000n, toBlock: 20100000n });
 ```
 
-## Vault (Token Vesting)
+## Read Token Info
 
 ```typescript
-// Check vault allocation
-const allocation = await liquid.getVaultAllocation(tokenAddress);
-console.log("Total:", allocation.amountTotal);
-console.log("Claimed:", allocation.amountClaimed);
-console.log("Lockup ends:", new Date(Number(allocation.lockupEndTime) * 1000));
+const info = await liquid.getTokenInfo(tokenAddress);
+console.log(info.name, info.symbol, info.decimals);
+console.log("Hook:", info.deployment.hook);
+console.log("Locker:", info.deployment.locker);
+```
 
-// Check claimable amount
-const claimable = await liquid.getVaultClaimable(tokenAddress);
+## Claim Fees & Rewards
 
-// Claim vested tokens
-const txHash = await liquid.claimVault(tokenAddress);
+```typescript
+// LP Rewards
+const rewards = await liquid.getTokenRewards(tokenAddress);
+await liquid.collectRewards(tokenAddress);
+
+// Fee claims (all fees converted to ETH by default)
+const claimable = await liquid.getFeesToClaim(ownerAddress, tokenAddress);
+await liquid.claimFees(ownerAddress, tokenAddress);
 ```
 
-## Factory Status
+## Vault (Token Vesting)
 
 ```typescript
-// Check if factory is accepting new deployments
-const deprecated = await liquid.isFactoryDeprecated();
-
-// Check if a locker/hook pair is enabled
-const enabled = await liquid.isLockerEnabled(lockerAddress, hookAddress);
+const allocation = await liquid.getVaultAllocation(tokenAddress);
+const claimable = await liquid.getVaultClaimable(tokenAddress);
+await liquid.claimVault(tokenAddress);
 ```
 
 ## Constants & ABIs
@@ -159,20 +220,45 @@ All production addresses, fee parameters, and contract ABIs are exported:
 
 ```typescript
 import {
-  ADDRESSES,     // Liquid Protocol contract addresses
-  EXTERNAL,      // External protocol addresses (PoolManager, WETH, etc.)
-  FEE,           // Fee constants (denominator, protocol fee, max fees)
-  TOKEN,         // Token constants (supply, decimals, max extensions)
-  DEFAULT_CHAIN, // base chain object
+  ADDRESSES,        // Liquid Protocol contract addresses
+  EXTERNAL,         // External protocol addresses (PoolManager, WETH, etc.)
+  FEE,              // Fee constants (denominator, protocol fee, max fees)
+  TOKEN,            // Token constants (supply, decimals, max extensions)
+  DEFAULTS,         // Default deploy config (hook, fees, MEV, ticks)
+  POOL_POSITIONS,   // Position presets (Standard, Liquid)
+  DEFAULT_CHAIN,    // base chain object
   DEFAULT_CHAIN_ID, // 8453
 
+  // Tick math & positions
+  getTickFromMarketCapETH,
+  getTickFromMarketCapUSD,
+  marketCapFromTickETH,
+  marketCapFromTickUSD,
+  createPositions,
+  createPositionsUSD,
+  createDefaultPositions,
+  describePositions,
+
+  // Encoding helpers
+  encodeStaticFeePoolData,
+  encodeDynamicFeePoolData,
+  encodeSniperAuctionData,
+
   // ABIs for direct contract interaction
   LiquidFactoryAbi,
   LiquidFeeLockerAbi,
   LiquidHookDynamicFeeV2Abi,
+  LiquidLpLockerAbi,
   LiquidVaultAbi,
+  LiquidSniperAuctionV2Abi,
+  LiquidSniperUtilV2Abi,
+  LiquidAirdropV2Abi,
+  LiquidTokenAbi,
+  LiquidUniv4EthDevBuyAbi,
+  LiquidPoolExtensionAllowlistAbi,
+  LiquidMevBlockDelayAbi,
   ERC20Abi,
-} from "liquid-protocol-sdk";
+} from "liquid-sdk";
 ```
 
 ## API Reference
@@ -182,31 +268,65 @@ import {
 #### Constructor
 
 ```typescript
-new LiquidSDK({ publicClient, walletClient? })
+new LiquidSDK({ walletClient, publicClient? })
 ```
 
-- `publicClient` (required) - viem `PublicClient` connected to Base
 - `walletClient` (optional) - viem `WalletClient` for write operations
+- `publicClient` (optional) - viem `PublicClient` connected to Base (auto-created if omitted)
 
 #### Methods
 
-| Method | Description | Requires Wallet |
-|--------|-------------|:-:|
-| `deployToken(params)` | Deploy a new token + pool | Yes |
-| `getDeploymentInfo(token)` | Get deployment info (hook, locker, extensions) | No |
-| `getTokenInfo(token)` | Get ERC20 info + deployment details | No |
-| `getPoolConfig(poolId, hook?)` | Get dynamic fee pool configuration | No |
-| `getPoolFeeState(poolId, hook?)` | Get current fee state variables | No |
-| `getPoolCreationTimestamp(poolId, hook?)` | Get pool creation timestamp | No |
-| `isLiquidToken0(poolId, hook?)` | Check if Liquid token is currency0 | No |
-| `getAvailableFees(owner, feeToken?)` | Get available fee balance (defaults to WETH) | No |
-| `getFeesToClaim(owner, feeToken?)` | Get claimable fee balance (defaults to WETH) | No |
-| `claimFees(owner, feeToken?)` | Claim accumulated fees (defaults to WETH) | Yes |
-| `getVaultAllocation(token)` | Get vault vesting allocation | No |
-| `getVaultClaimable(token)` | Get vested amount available to claim | No |
-| `claimVault(token)` | Claim vested tokens from vault | Yes |
-| `isFactoryDeprecated()` | Check if factory is deprecated | No |
-| `isLockerEnabled(locker, hook)` | Check if locker/hook pair is enabled | No |
+| Method | Description | Wallet |
+|--------|-------------|:------:|
+| **Deployment** | | |
+| `deployToken(params)` | Deploy token + Uniswap V4 pool | Yes |
+| `buildDevBuyExtension(devBuy)` | Build dev buy extension config | No |
+| **Token Discovery** | | |
+| `getTokens(options?)` | Query deployed tokens with filters | No |
+| `getTokenEvent(token)` | Look up single token (indexed, fast) | No |
+| `getDeployedTokens(deployer)` | Get tokens by deployer | No |
+| **Token Info** | | |
+| `getDeploymentInfo(token)` | Hook, locker, extensions | No |
+| `getTokenInfo(token)` | ERC20 info + deployment details | No |
+| **Token Updates** | | |
+| `updateImage(token, url)` | Update token image (admin) | Yes |
+| `updateMetadata(token, json)` | Update token metadata (admin) | Yes |
+| **Pool State** | | |
+| `getPoolConfig(poolId)` | Dynamic fee pool configuration | No |
+| `getPoolFeeState(poolId)` | Current fee state variables | No |
+| `getPoolCreationTimestamp(poolId)` | Pool creation timestamp | No |
+| `isLiquidToken0(poolId)` | Token sort order in pool | No |
+| **Fee Claims** | | |
+| `getAvailableFees(owner, token)` | Total unlocked fees | No |
+| `getFeesToClaim(owner, token)` | Claimable fee balance | No |
+| `claimFees(owner, token)` | Claim accumulated fees | Yes |
+| **LP Rewards** | | |
+| `getTokenRewards(token)` | Reward config (recipients, bps, poolKey) | No |
+| `collectRewards(token)` | Collect + unlock LP fees | Yes |
+| `collectRewardsWithoutUnlock(token)` | Collect fees only | Yes |
+| `updateRewardRecipient(token, idx, addr)` | Change reward recipient | Yes |
+| **Vault** | | |
+| `getVaultAllocation(token)` | Vault vesting state | No |
+| `getVaultClaimable(token)` | Vested amount available | No |
+| `claimVault(token)` | Claim vested tokens | Yes |
+| **Airdrop** | | |
+| `getAirdropInfo(token)` | Airdrop state | No |
+| `getAirdropClaimable(token, recipient, amount)` | Claimable for recipient | No |
+| `claimAirdrop(token, recipient, amount, proof)` | Claim airdrop | Yes |
+| **Sniper Auction** | | |
+| `getAuctionState(poolId)` | Round, gasPeg, fee, nextBlock | No |
+| `getAuctionFeeConfig(poolId)` | Fee decay parameters | No |
+| `getAuctionDecayStartTime(poolId)` | When fee decay started | No |
+| `getAuctionMaxRounds()` | Max auction rounds | No |
+| `getAuctionGasPriceForBid(gasPeg, bid)` | Calculate gas price for bid | No |
+| `bidInAuction(params, gasPrice)` | Bid + swap (auto-wraps WETH) | Yes |
+| **MEV Protection** | | |
+| `getMevBlockDelay()` | Configured block delay | No |
+| `getPoolUnlockTime(poolId)` | When MEV lock expires | No |
+| **Factory** | | |
+| `isFactoryDeprecated()` | Factory still active? | No |
+| `isLockerEnabled(locker, hook)` | Locker/hook pair enabled? | No |
+| `isExtensionEnabled(extension)` | Extension on allowlist? | No |
 
 ## Production Addresses
 
@@ -214,18 +334,18 @@ All contracts are deployed on **Base** (chain ID 8453):
 
 | Contract | Address |
 |----------|---------|
-| Factory | `0x0000003482fe299E72d4908368044A8A173BE576` |
-| Hook Dynamic Fee V2 | `0x2A2F73CDDa098d639bd8Bbcd7dF2bf24E06728cC` |
-| Hook Static Fee V2 | `0xb2401c5369AaCF62F8d615623C7F68F84da428Cc` |
-| Fee Locker | `0x000008B9242b7e4432f6c4b1EeAD93562f9Cc94d` |
-| LP Locker | `0x00000548732DfA56Be1257cE44D0CFc3B46dDb2A` |
-| LP Locker Fee Conversion | `0x00000547518784420CEeF761fb18D884bb908102` |
-| Vault | `0x000001c5263F4d64CdC343cDA9C8bF961CF8376c` |
-| Sniper Auction V2 | `0x000007b64003ee07a69576F98859a0a36b854260` |
-| Sniper Util V2 | `0x000003Ee0cb9B0C82C6C7FCB7b81a9883F285270` |
-| MEV Block Delay | `0x0000035D83588954F3c581c3A66251b3F06AD5e4` |
-| Airdrop V2 | `0x00000C222442512b08446D33dd9754a7F260BE79` |
-| Pool Extension Allowlist | `0x000003Afb1b070F037D2871eE0A6b8c8f53F7B77` |
+| Factory | `0x04F1a284168743759BE6554f607a10CEBdB77760` |
+| Hook Dynamic Fee V2 | `0x80E2F7dC8C2C880BbC4BDF80A5Fb0eB8B1DB68CC` |
+| Hook Static Fee V2 | `0x9811f10Cd549c754Fa9E5785989c422A762c28cc` |
+| Fee Locker | `0xF7d3BE3FC0de76fA5550C29A8F6fa53667B876FF` |
+| LP Locker Fee Conversion | `0x77247fCD1d5e34A3703AcA898A591Dc7422435f3` |
+| Vault | `0xdFCCC93257c20519A9005A2281CFBdF84836d50E` |
+| Sniper Auction V2 | `0x187e8627c02c58F31831953C1268e157d3BfCefd` |
+| Sniper Util V2 | `0x2B6cd5Be183c388Dd0074d53c52317df1414cd9f` |
+| MEV Descending Fees | `0x8D6B080e48756A99F3893491D556B5d6907b6910` |
+| Airdrop V2 | `0x1423974d48f525462f1c087cBFdCC20BDBc33CdD` |
+| Pool Extension Allowlist | `0xb614167d79aDBaA9BA35d05fE1d5542d7316Ccaa` |
+| Univ4 ETH Dev Buy | `0x5934097864dC487D21A7B4e4EEe201A39ceF728D` |
 
 ## License
 

package/dist/index.d.mts

@@ -471,6 +471,9 @@ declare const ADDRESSES: {
 declare const EXTERNAL: {
     readonly POOL_MANAGER: Address;
     readonly WETH: Address;
+    /** DIEM — Liquid's intelligence-economy token. Also a pair token for
+     *  agent-token launches (see `createLiquidPositionsUSD`). */
+    readonly DIEM: Address;
     readonly UNIVERSAL_ROUTER: Address;
     readonly PERMIT2: Address;
 };
@@ -621,31 +624,7 @@ declare const DEFAULT_CHAIN: {
     formatters: {
         readonly block: {
             exclude: [] | undefined;
-            format: (args: viem_chains.OpStackRpcBlock, action
-            /**
-             * Pre-built position configurations.
-             *
-             * - **Standard**: Single position covering full range (~$20K → $1.5B).
-             *   Default starting tick -230400 (≈10 ETH market cap).
-             *
-             * - **Liquid**: 3-tranche default for Liquid Protocol.
-             *   Hardcoded for ≈10 ETH start at ~$2070/ETH.
-             *   For dynamic market cap targets, use `createPositionsUSD()` instead.
-             *
-             * Note: positionBps must sum to 10,000 (100%).
-             */
-            ? /**
-             * Pre-built position configurations.
-             *
-             * - **Standard**: Single position covering full range (~$20K → $1.5B).
-             *   Default starting tick -230400 (≈10 ETH market cap).
-             *
-             * - **Liquid**: 3-tranche default for Liquid Protocol.
-             *   Hardcoded for ≈10 ETH start at ~$2070/ETH.
-             *   For dynamic market cap targets, use `createPositionsUSD()` instead.
-             *
-             * Note: positionBps must sum to 10,000 (100%).
-             */: string | undefined) => {
+            format: (args: viem_chains.OpStackRpcBlock, action?: string | undefined) => {
                 baseFeePerGas: bigint | null;
                 blobGasUsed: bigint;
                 difficulty: bigint;
@@ -2323,6 +2302,7 @@ declare function getTickFromMarketCapStable(marketCap: number, stableDecimals: n
  * market cap milestones. Percentages represent share of the *pool supply*
  * (i.e. after dev buy, airdrop, and vault allocations are deducted).
  */
+
 interface MarketCapTranche {
     /** Upper bound market cap in ETH for this tranche */
     upperMarketCapETH: number;
@@ -2418,6 +2398,55 @@ declare function createPositionsUSD(startingMarketCapUSD: number, ethPriceUSD: n
 declare function createDefaultPositions(startingMarketCapUSD: number, ethPriceUSD: number, tickSpacing?: number): PositionArrays & {
     tickIfToken0IsLiquid: number;
 };
+/**
+ * Shift every tick in a position layout by a fixed amount, preserving the
+ * positionBps splits. The primitive behind `createLiquidPositionsUSD` — it
+ * re-anchors a fixed-shape layout (e.g. `POOL_POSITIONS.Liquid`) to a
+ * different starting tick.
+ *
+ * `shiftBy` should be a multiple of the pool's tick spacing so the shifted
+ * ticks stay aligned. A difference of two aligned ticks is always aligned,
+ * so deriving it as `targetTick - sourceBottomTick` is safe.
+ *
+ * @param positions - Source positions (e.g. `POOL_POSITIONS.Liquid`)
+ * @param shiftBy - Ticks to add to every tickLower/tickUpper (may be negative)
+ * @returns A fresh array — the source is not mutated
+ */
+declare function shiftPositions(positions: readonly PoolPosition[], shiftBy: number): PoolPosition[];
+/**
+ * Build the canonical 5-position "Liquid" layout (10/50/15/20/5) re-anchored
+ * to a starting market cap, denominated in the *paired token's* USD price.
+ *
+ * Works for any pair token — pass the price of whatever the pool is paired
+ * against:
+ *   - WETH-paired: `createLiquidPositionsUSD(20_000, ethPriceUSD)`
+ *   - DIEM-paired: `createLiquidPositionsUSD(20_000, diemPriceUSD)`
+ *
+ * Unlike `createDefaultPositions` (a 3-tranche layout), this preserves the
+ * exact shape of `POOL_POSITIONS.Liquid` — the same curve `deployToken()`
+ * uses by default — just shifted so its bottom sits at the requested start.
+ *
+ * @param startingMarketCapUSD - Initial market cap in USD
+ * @param pairedTokenPriceUSD - USD price of the token the pool is paired against
+ * @param tickSpacing - Tick spacing (default 200)
+ * @returns Position arrays + `tickIfToken0IsLiquid`, ready to spread into `deployToken()`
+ *
+ * @example
+ * ```ts
+ * import { LiquidSDK, EXTERNAL, createLiquidPositionsUSD } from "liquid-sdk";
+ *
+ * const positions = createLiquidPositionsUSD(20_000, diemPriceUSD);
+ * await sdk.deployToken({
+ *   name: "Agent Token",
+ *   symbol: "AGENT",
+ *   pairedToken: EXTERNAL.DIEM,
+ *   ...positions,
+ * });
+ * ```
+ */
+declare function createLiquidPositionsUSD(startingMarketCapUSD: number, pairedTokenPriceUSD: number, tickSpacing?: number): PositionArrays & {
+    tickIfToken0IsLiquid: number;
+};
 /**
  * Describe positions as human-readable market cap ranges.
  * Useful for displaying position info in UIs.
@@ -2595,4 +2624,4 @@ declare function parseContext(contextString: string): LiquidContext | null;
  */
 declare function parseMetadata(metadataString: string): LiquidMetadata | null;
 
-export { ADDRESSES, type AirdropExtensionParams, type AirdropInfo, type BidInAuctionParams, type BidInAuctionResult, DEFAULTS, DEFAULT_CHAIN, DEFAULT_CHAIN_ID, DEFAULT_RPC_URL, DEFAULT_TRANCHES_USD, type DeployTokenParams, type DeployTokenResult, type DeploymentConfig, type DeploymentInfo, type DevBuyParams, type DynamicFeeConfig, ERC20Abi, EXTERNAL, type ExtensionConfig, FEE, FeePreference, type GetTokensOptions, LiquidAirdropV2Abi, type LiquidContext, LiquidFactoryAbi, LiquidFeeLockerAbi, LiquidHookDynamicFeeV2Abi, LiquidLpLockerAbi, type LiquidMetadata, LiquidMevBlockDelayAbi, LiquidMevDescendingFeesAbi, LiquidPoolExtensionAllowlistAbi, LiquidSDK, type LiquidSDKConfig, LiquidSniperAuctionV2Abi, LiquidSniperUtilV2Abi, LiquidTokenAbi, LiquidUniv4EthDevBuyAbi, LiquidVaultAbi, type LockerConfig, type MarketCapTranche, type MarketCapTrancheUSD, type MevModuleConfig, POOL_POSITIONS, type PoolConfig, type PoolDynamicConfigVars, type PoolDynamicFeeVars, type PoolKey, type PoolPosition, type PositionArrays, type PositionConfig, type SniperAuctionConfig, type SniperAuctionFeeConfig, type SniperAuctionState, type SocialMediaUrl, TOKEN, type TokenConfig, type TokenCreatedEvent, type TokenRewardInfo, type VaultAllocation, type VaultExtensionParams, buildContext, buildMetadata, createDefaultPositions, createPositions, createPositionsUSD, describePositions, encodeDynamicFeePoolData, encodeFeeConversionLockerData, encodeSniperAuctionData, encodeStaticFeePoolData, getTickFromMarketCapETH, getTickFromMarketCapStable, getTickFromMarketCapUSD, marketCapFromTickETH, marketCapFromTickUSD, parseContext, parseMetadata };
+export { ADDRESSES, type AirdropExtensionParams, type AirdropInfo, type BidInAuctionParams, type BidInAuctionResult, DEFAULTS, DEFAULT_CHAIN, DEFAULT_CHAIN_ID, DEFAULT_RPC_URL, DEFAULT_TRANCHES_USD, type DeployTokenParams, type DeployTokenResult, type DeploymentConfig, type DeploymentInfo, type DevBuyParams, type DynamicFeeConfig, ERC20Abi, EXTERNAL, type ExtensionConfig, FEE, FeePreference, type GetTokensOptions, LiquidAirdropV2Abi, type LiquidContext, LiquidFactoryAbi, LiquidFeeLockerAbi, LiquidHookDynamicFeeV2Abi, LiquidLpLockerAbi, type LiquidMetadata, LiquidMevBlockDelayAbi, LiquidMevDescendingFeesAbi, LiquidPoolExtensionAllowlistAbi, LiquidSDK, type LiquidSDKConfig, LiquidSniperAuctionV2Abi, LiquidSniperUtilV2Abi, LiquidTokenAbi, LiquidUniv4EthDevBuyAbi, LiquidVaultAbi, type LockerConfig, type MarketCapTranche, type MarketCapTrancheUSD, type MevModuleConfig, POOL_POSITIONS, type PoolConfig, type PoolDynamicConfigVars, type PoolDynamicFeeVars, type PoolKey, type PoolPosition, type PositionArrays, type PositionConfig, type SniperAuctionConfig, type SniperAuctionFeeConfig, type SniperAuctionState, type SocialMediaUrl, TOKEN, type TokenConfig, type TokenCreatedEvent, type TokenRewardInfo, type VaultAllocation, type VaultExtensionParams, buildContext, buildMetadata, createDefaultPositions, createLiquidPositionsUSD, createPositions, createPositionsUSD, describePositions, encodeDynamicFeePoolData, encodeFeeConversionLockerData, encodeSniperAuctionData, encodeStaticFeePoolData, getTickFromMarketCapETH, getTickFromMarketCapStable, getTickFromMarketCapUSD, marketCapFromTickETH, marketCapFromTickUSD, parseContext, parseMetadata, shiftPositions };