liquid-sdk 1.6.1 → 1.6.3

package/AGENT_README.md

@@ -54,7 +54,7 @@ Requires wallet. Creates the token, pool, locks LP, and optionally buys tokens a
 const result = await sdk.deployToken({
   name: "My Token",
   symbol: "MTK",
-  image: "https://example.com/logo.png",     // optional
+  image: "ipfs://QmYourImageCID",              // optional, IPFS recommended
   metadata: '{"description":"A cool token"}', // optional, JSON string
   context: '{"platform":"my-app"}',           // optional, tracking/attribution
 
@@ -642,7 +642,7 @@ const sdk = new LiquidSDK({ publicClient, walletClient });
 const result = await sdk.deployToken({
   name: "Agent Token",
   symbol: "AGENT",
-  image: "https://example.com/logo.png",
+  image: "ipfs://QmYourImageCID",
   metadata: JSON.stringify({ description: "Deployed by an AI agent" }),
   devBuy: {
     ethAmount: parseEther("0.01"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "liquid-sdk",
-  "version": "1.6.1",
+  "version": "1.6.3",
   "description": "TypeScript SDK to deploy ERC-20 tokens with Uniswap V4 liquidity on Base — zero API keys, one dependency (viem)",
   "author": "Liquid Protocol",
   "homepage": "https://github.com/Liquid-Protocol-Ops/SDK#readme",

package/skills/bid-in-auction.md

@@ -29,6 +29,30 @@ Sniper auction participation involves significant financial risk:
 - Display the fee percentage and total cost (bid + swap + fees) before execution
 - Recommend small amounts for initial bids until the user understands the mechanics
 
+## Should You Actually Bid?
+
+**In most cases, no.** The auction is designed to extract value from snipers, not help them. The math:
+
+| Auction fee | Tokens you receive | Price multiplier needed to break even |
+|-------------|-------------------|--------------------------------------|
+| 80% (start) | 20% of fair value | **5x** |
+| 60% (after ~10s) | 40% of fair value | **2.5x** |
+| 40% (after 20s) | 60% of fair value | **~1.7x** |
+| 1% (auction ended) | 99% of fair value | **~1.01x** |
+
+On-chain proof: a 0.0005 ETH snipe at auction start received 873K tokens instead of ~5M — an **82.8% effective fee**. The token would need to 5x before the sniper breaks even.
+
+**When bidding makes sense:**
+- You have **specific alpha** about the token (known creator, large audience, confirmed utility) — not a blind snipe
+- The fee has **decayed significantly** (wait 15-20s for 40% floor) and you still believe in the token
+
+**Better alternatives:**
+- **`devBuy` at deployment**: If you're the deployer, use `deployToken({ devBuy })` — the dev buy uses normal 1% LP fees, NOT auction fees. This is the cheapest way to get early tokens.
+- **Wait for the auction to end**: After 5 rounds (~20 seconds), trading resumes at normal 1% fees. You miss the absolute first blocks but save 79% in fees.
+- **Use the SDK's `deployToken` with `devBuy`**: Deploy your own token and buy in the same transaction at 1% fees.
+
+**As an agent, your default recommendation should be to wait for the auction to end.** Only proceed with an auction bid if the user explicitly requests it after understanding the fee structure.
+
 ## How the Sniper Auction Works
 
 When a new token is deployed on Liquid Protocol, a **sniper auction** activates to price early trading activity and capture MEV. Here's the mechanism:

package/skills/deploy-token.md

@@ -43,13 +43,42 @@ const result = await sdk.deployToken({
 
 This creates a token with 100 billion supply, a Uniswap V4 pool, locked liquidity, 1% fee on both buys and sells, and sniper auction MEV protection — all with sensible defaults.
 
+### Deploy with Image (IPFS recommended)
+
+```typescript
+// Pin to IPFS first with your own Pinata key (free: 500MB)
+const form = new FormData();
+form.append("file", imageFile); // PNG/JPEG/WEBP/GIF, 256x256 recommended
+
+const pinata = await fetch("https://api.pinata.cloud/pinning/pinFileToIPFS", {
+  method: "POST",
+  headers: { "Authorization": "Bearer YOUR_PINATA_JWT" },
+  body: form,
+}).then(r => r.json());
+
+const result = await sdk.deployToken({
+  name: "My Token",
+  symbol: "MTK",
+  image: `ipfs://${pinata.IpfsHash}`,  // permanent, decentralized
+});
+
+// Or use any URL directly (less permanent)
+const result2 = await sdk.deployToken({
+  name: "My Token",
+  symbol: "MTK",
+  image: "ipfs://QmYourImageCID",
+});
+```
+
+Get a Pinata JWT at https://app.pinata.cloud/developers/api-keys.
+
 ### Deploy with Dev Buy (buy tokens at launch)
 
 ```typescript
 const result = await sdk.deployToken({
   name: "My Token",
   symbol: "MTK",
-  image: "https://example.com/logo.png",
+  image: "ipfs://QmYourImageCID",
   metadata: JSON.stringify({ description: "Launched by an AI agent" }),
   devBuy: {
     ethAmount: parseEther("0.01"), // ETH to spend buying tokens at launch

package/skills/sdk-overview.md

@@ -44,7 +44,7 @@ These fields define how the token appears in wallets, aggregators, and explorers
 const result = await sdk.deployToken({
   name: "My Project Token",                    // Token name (required)
   symbol: "MPT",                               // Token symbol (required)
-  image: "https://example.com/logo.png",       // Logo URL (shown in wallets)
+  image: "ipfs://QmYourImageCID",              // IPFS URI (recommended) or HTTPS URL
   metadata: buildMetadata({                    // Rich metadata (JSON, on-chain)
     description: "A community token for builders on Base",
     socialMediaUrls: [
@@ -77,6 +77,43 @@ await sdk.updateMetadata(tokenAddress, buildMetadata({
 }));
 ```
 
+### Image Upload (IPFS)
+
+Token images should be pinned to IPFS for permanence. The `image` field in `deployToken()` accepts any string — use an `ipfs://` URI for permanent storage.
+
+**Pin with your own Pinata key:**
+
+```typescript
+// 1. Pin image to IPFS via Pinata (your own API key)
+const form = new FormData();
+form.append("file", imageFile); // PNG, JPEG, WEBP, or GIF
+
+const res = await fetch("https://api.pinata.cloud/pinning/pinFileToIPFS", {
+  method: "POST",
+  headers: { "Authorization": "Bearer YOUR_PINATA_JWT" },
+  body: form,
+});
+const { IpfsHash } = await res.json();
+const ipfsUri = `ipfs://${IpfsHash}`;
+
+// 2. Deploy with IPFS image
+await sdk.deployToken({
+  name: "My Token",
+  symbol: "MTK",
+  image: ipfsUri, // stored on-chain permanently
+});
+```
+
+Get a Pinata JWT at https://app.pinata.cloud/developers/api-keys (free tier: 500MB).
+
+**Recommended:** 256x256 or 512x512 PNG, square. This is the standard size for DexScreener, wallet apps, and token lists.
+
+**Accepted formats:** PNG, JPEG, WEBP, GIF.
+
+You can also use any `https://` URL — the `image` field accepts any string. But IPFS URIs are preferred because they're permanent and decentralized.
+
+---
+
 ### Token Metadata Schema
 
 Stored in the `tokenMetadata` field of the `TokenCreated` event. Wallets (Rainbow, Coinbase Wallet) and aggregators (Matcha, 0x) read this.
@@ -278,7 +315,7 @@ Only the token admin can update image and metadata after deployment.
 
 ```typescript
 // Update image
-await sdk.updateImage(tokenAddress, "https://new-image.example.com/logo.png");
+await sdk.updateImage(tokenAddress, "ipfs://QmNewImageCID...");
 
 // Update metadata
 await sdk.updateMetadata(tokenAddress, buildMetadata({