logiqical 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,185 @@
+# logiqical
+
+The complete SDK for AI agents trading on Avalanche. Swaps, staking, launchpad, token launches, DEX — one package, zero config.
+
+## Install
+
+```bash
+npm install logiqical
+```
+
+## Quick Start
+
+```typescript
+import { LogiqicalClient } from "logiqical";
+
+const client = new LogiqicalClient({ wallet: "0xYourWallet" });
+// Auto-registers API key on first call. No setup needed.
+
+// Check balances
+const bal = await client.swap.getBalances("0xYourWallet");
+
+// Discover trending launchpad tokens
+const hot = await client.launchpad.getTopVolume("24h");
+
+// Launch your own token on Arena
+const launch = await client.launchpad.launch(wallet, "My Token", "MTK", imageBase64);
+
+// Buy a graduated token via Arena DEX
+const buy = await client.launchpad.buildBuy(wallet, tokenId, "0.1");
+
+// Swap any token pair
+const tx = await client.dex.buildSwap(wallet, "AVAX", "USDC", "1.0");
+
+// Sign & broadcast
+await client.broadcast(signedTx);
+```
+
+## Modules
+
+### `client.swap` — ARENA Token Swaps
+
+| Method | Description |
+|--------|-------------|
+| `getBalances(wallet)` | AVAX and ARENA balances |
+| `quote(avax)` | Quote AVAX → ARENA |
+| `sellQuote(arena)` | Quote ARENA → AVAX |
+| `buildBuy(wallet, avax, slippage?)` | Build buy transaction |
+| `buildSell(wallet, amount, slippage?)` | Build sell transaction (`"max"` for all) |
+
+### `client.staking` — Stake ARENA for Rewards
+
+| Method | Description |
+|--------|-------------|
+| `getInfo(wallet)` | Staked amount, pending rewards, APY |
+| `buildStake(wallet, amount)` | Stake ARENA tokens |
+| `buildBuyAndStake(wallet, avax, slippage?)` | Buy + stake in one flow |
+| `buildUnstake(wallet, amount)` | Unstake and claim rewards |
+
+### `client.launchpad` — Token Discovery, Trading & Launch
+
+#### Discovery
+| Method | Description |
+|--------|-------------|
+| `getRecent(count?, type?)` | Latest launched tokens |
+| `getTopVolume(timeframe?, count?)` | Trending by volume (5m/1h/4h/24h) |
+| `getGraduating(count?)` | Tokens about to graduate to DEX |
+| `getGraduated(count?)` | Already graduated tokens |
+| `search(query)` | Find by name, symbol, or address |
+
+#### Intelligence
+| Method | Description |
+|--------|-------------|
+| `getToken(tokenId?, address?)` | Full token profile + stats |
+| `getHolders(address?, tokenId?, count?)` | Top holders with PnL |
+| `getActivity(tokenId?, address?, count?)` | Recent trade history |
+| `getTrades(count?, offset?)` | Global trade feed |
+| `quote(tokenId, side, amount)` | Bonding curve quote |
+| `getPortfolio(wallet)` | Your tracked positions |
+| `getMarketCap(tokenId)` | Market cap breakdown |
+| `getOverview()` | Platform stats |
+
+#### Trading
+| Method | Description |
+|--------|-------------|
+| `buildBuy(wallet, tokenId, avax, slippage?)` | Buy launchpad token (auto-routes graduated tokens via Arena DEX) |
+| `buildSell(wallet, tokenId, amount, slippage?)` | Sell (`"max"` for all, auto-routes graduated) |
+
+#### Token Launch
+| Method | Description |
+|--------|-------------|
+| `launch(wallet, name, symbol, imageBase64?, paymentToken?, initialBuyAvax?)` | Full token launch — uploads image, creates Arena community, returns createToken tx |
+| `uploadImage(imageBase64, fileType?)` | Upload token image to Arena CDN |
+| `buildCreate(wallet, name, symbol, paymentToken?, initialBuyAvax?)` | Build only the createToken tx |
+
+### `client.dex` — Swap Any Avalanche Token
+
+| Method | Description |
+|--------|-------------|
+| `getTokens()` | List 14+ known tokens |
+| `getTokenInfo(address)` | On-chain token info |
+| `quote(from, to, amount)` | Quote any pair |
+| `getBalance(wallet, token)` | Any token balance |
+| `buildSwap(wallet, from, to, amount, slippage?)` | Swap any pair |
+
+### System
+
+| Method | Description |
+|--------|-------------|
+| `client.broadcast(signedTx)` | Broadcast signed transaction |
+| `client.health()` | API health check |
+| `client.getInstructions()` | Full agent documentation |
+
+## Token Launch Flow
+
+Agents can launch their own tokens on Arena with a single SDK call:
+
+```typescript
+import { readFileSync } from "fs";
+
+const imageBase64 = readFileSync("token-logo.jpg").toString("base64");
+
+const result = await client.launchpad.launch(
+  "0xYourWallet",
+  "My Token",        // token name
+  "MTK",             // ticker symbol
+  imageBase64,       // token image (optional)
+  "arena",           // "arena" or "avax" paired
+);
+
+// result.transaction — unsigned createToken tx to sign & broadcast
+// result.community — Arena community metadata
+// result.imageUrl — hosted image URL
+// result.instructions — step-by-step next actions
+```
+
+## Graduated Token Trading
+
+Tokens that graduate from the bonding curve automatically trade via Arena's DEX router. The SDK handles this seamlessly — `buildBuy` and `buildSell` detect graduation and route through Arena's Uniswap V4 pools + Yield Yak aggregator.
+
+```typescript
+// Works for both bonding curve AND graduated tokens
+const buy = await client.launchpad.buildBuy(wallet, tokenId, "0.5");
+// → Routes via bonding curve OR Arena DEX automatically
+```
+
+## How It Works
+
+1. **Install** — `npm install logiqical`
+2. **Initialize** — pass your wallet address
+3. **Trade** — the SDK auto-registers an API key, builds unsigned transactions, you sign and broadcast
+
+All `build*` methods return unsigned transactions. Sign them with your private key, then call `client.broadcast(signedTx)`. If multiple transactions are returned (e.g. approve + swap), execute them **in order** and wait for each to confirm.
+
+## Configuration
+
+```typescript
+const client = new LogiqicalClient({
+  wallet: "0x...",        // Required: your agent's wallet
+  apiKey: "arena_...",    // Optional: skip auto-registration
+  baseUrl: "https://...", // Optional: custom API URL
+  name: "my-agent",      // Optional: agent display name
+});
+```
+
+## Features
+
+- **Zero config** — just pass a wallet address
+- **Auto-registration** — API key created on first call
+- **Full TypeScript** — every method and response is typed
+- **JSDoc everywhere** — AI agents understand methods from hover info
+- **Zero dependencies** — uses native `fetch` (Node 18+)
+- **CJS + ESM** — works with `require()` and `import`
+- **35+ methods** across 4 modules
+- **Token launches** — create tokens on Arena with image upload
+- **Smart routing** — graduated tokens auto-route via Arena DEX
+
+## Built on
+
+- [Avalanche C-Chain](https://avax.network)
+- [Arena](https://arena.social)
+- [Arena DEX Router](https://snowtrace.io/address/0xDE9D7290959b6060860b983b32f2d65b2701EBC2)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -195,6 +195,32 @@ interface LaunchpadSellResponse {
     summary?: string;
     note?: string;
 }
+interface ArenaCommunity {
+    id: string;
+    signer: string;
+    isTemporary: boolean;
+    name: string;
+    tokenName: string;
+    ticker: string;
+    photoURL: string;
+    paymentToken: string;
+    contractAddress: string | null;
+    createdOn: string;
+}
+interface LaunchTokenResponse {
+    community: ArenaCommunity;
+    imageUrl: string;
+    transaction: UnsignedTx;
+    nextTokenId: string;
+    instructions: string[];
+}
+interface UploadImageResponse {
+    imageUrl: string;
+}
+interface BuildCreateResponse {
+    transaction: UnsignedTx;
+    nextTokenId: string;
+}
 interface DexTokenEntry {
     symbol: string;
     address: string;
@@ -230,6 +256,115 @@ interface DexSwapResponse {
     transactions: UnsignedTx[];
     summary: string;
 }
+interface PerpsSetupResponse {
+    success: boolean;
+    message: string;
+}
+interface PerpsTradingPair {
+    provider: string;
+    dex: string;
+    name: string;
+    symbol: string;
+    icon: string;
+    baseAssetId: number;
+    baseAsset: string;
+    quoteAsset: string;
+    sizePrecision: number;
+    pricePrecision: number;
+    maxLeverage: number;
+    isDelisted: boolean;
+    isOnlyIsolated: boolean;
+    marginMode: string;
+}
+interface PerpsTradingPairsResponse {
+    pairs: PerpsTradingPair[];
+    cachedAt: string;
+    count: number;
+}
+interface PerpsOrderResponse {
+    [key: string]: any;
+}
+interface PerpsPositionsResponse {
+    assetPositions?: any[];
+    marginSummary?: {
+        accountValue: string;
+        totalMarginUsed: string;
+        totalNtlPos: string;
+        totalRawUsd: string;
+    };
+    [key: string]: any;
+}
+interface BridgeTransaction {
+    to: string;
+    data: string;
+    value: string;
+    gasLimit?: string;
+    chainId: number;
+}
+interface BridgeQuoteResponse {
+    id: string;
+    fromChainId: number;
+    toChainId: number;
+    fromToken: string;
+    toToken: string;
+    fromAmount: string;
+    toAmount: string;
+    estimatedGas: string;
+    estimatedTime: number;
+    tool: string;
+    transaction?: BridgeTransaction;
+}
+interface BridgeRoutesResponse {
+    routes: BridgeQuoteResponse[];
+    count: number;
+}
+interface BridgeStatusResponse {
+    status: "NOT_FOUND" | "PENDING" | "DONE" | "FAILED";
+    substatus?: string;
+    receiving?: {
+        txHash: string;
+        amount: string;
+        token: string;
+        chainId: number;
+    };
+}
+interface BridgeLiFiToken {
+    address: string;
+    symbol: string;
+    decimals: number;
+    name: string;
+    priceUSD?: string;
+    chainId: number;
+}
+interface BridgeLiFiChain {
+    id: number;
+    key: string;
+    name: string;
+    chainType: string;
+    nativeToken?: {
+        symbol: string;
+        decimals: number;
+        address: string;
+    };
+}
+interface BridgeTokensResponse {
+    tokens: Record<string, BridgeLiFiToken[]>;
+}
+interface BridgeTokenResponse extends BridgeLiFiToken {
+}
+interface BridgeChainsResponse {
+    chains: BridgeLiFiChain[];
+    count: number;
+}
+interface BridgeConnectionsResponse {
+    connections: any[];
+}
+interface BridgeInfoResponse {
+    chains: Record<string, number>;
+    usdc: Record<string, string>;
+    nativeToken: string;
+    tip: string;
+}
 interface RegisterResponse {
     apiKey: string;
     wallet: string;
@@ -407,6 +542,36 @@ declare class LaunchpadModule {
      * @param offset - Pagination offset
      */
     getTrades(count?: number, offset?: number): Promise<GlobalTradesResponse>;
+    /**
+     * Launch a new token on Arena — uploads image, creates community, and returns the unsigned createToken transaction.
+     *
+     * @param wallet - Creator wallet address
+     * @param name - Token name (also used as community name)
+     * @param symbol - Token ticker symbol
+     * @param imageBase64 - Token image as base64 string (optional)
+     * @param paymentToken - "avax" or "arena" (default: "arena")
+     * @param initialBuyAvax - AVAX amount for initial buy at creation (default: "0")
+     */
+    launch(wallet: string, name: string, symbol: string, imageBase64?: string, paymentToken?: "avax" | "arena", initialBuyAvax?: string): Promise<LaunchTokenResponse>;
+    /**
+     * Upload a token image to Arena's CDN and get the hosted URL.
+     * Use this before launch() if you want to preview the image URL first.
+     *
+     * @param imageBase64 - Image as base64 string
+     * @param fileType - MIME type (default: "image/jpeg")
+     */
+    uploadImage(imageBase64: string, fileType?: string): Promise<UploadImageResponse>;
+    /**
+     * Build only the createToken transaction (no image or community creation).
+     * Useful if you want to handle image upload and community creation separately.
+     *
+     * @param wallet - Creator wallet address
+     * @param name - Token name
+     * @param symbol - Token ticker symbol
+     * @param paymentToken - "avax" or "arena" (default: "arena")
+     * @param initialBuyAvax - AVAX for initial buy (default: "0")
+     */
+    buildCreate(wallet: string, name: string, symbol: string, paymentToken?: "avax" | "arena", initialBuyAvax?: string): Promise<BuildCreateResponse>;
     /**
      * Build unsigned transaction to buy a launchpad token with AVAX.
      *
@@ -476,6 +641,151 @@ declare class DexModule {
     buildSwap(wallet: string, from: string, to: string, amount: string, slippage?: number): Promise<DexSwapResponse>;
 }
 
+declare class PerpsModule {
+    private http;
+    private auth;
+    constructor(http: HttpClient, auth: () => Promise<void>);
+    /**
+     * Link your Arena API key to enable perps trading.
+     * One-time setup — after this, all /perp endpoints work automatically.
+     * @param arenaApiKey - Your Arena API key (from arena.social)
+     */
+    setup(arenaApiKey: string): Promise<PerpsSetupResponse>;
+    /** Register for perps trading on Hyperliquid */
+    register(): Promise<any>;
+    /** Check perps registration status */
+    getRegistrationStatus(): Promise<any>;
+    /** Get your Hyperliquid API wallet address */
+    getWalletAddress(): Promise<any>;
+    /** Check which auth steps are completed */
+    getAuthStatus(): Promise<any>;
+    /**
+     * Get EIP-712 payload for an auth step.
+     * @param step - Auth step: "accept-terms", "approve-agent", "set-referrer", "approve-builder-fee"
+     * @param body - Optional body (accept-terms requires mainWalletAddress)
+     */
+    getAuthPayload(step: string, body?: any): Promise<any>;
+    /**
+     * Submit signed EIP-712 payload for an auth step.
+     * @param step - Auth step
+     * @param body - Signed payload with signature and metadata
+     */
+    submitAuthSignature(step: string, body: any): Promise<any>;
+    /** Enable HIP-3 abstraction (automated, no signature needed) */
+    enableHip3(): Promise<any>;
+    /** Get all available perpetual trading pairs (250+ markets) */
+    getTradingPairs(): Promise<PerpsTradingPairsResponse>;
+    /**
+     * Update leverage for a market. Must be called before first order.
+     * @param symbol - Market symbol (e.g. "BTC", "ETH")
+     * @param leverage - Leverage multiplier (1-50 depending on market)
+     * @param leverageType - "cross" or "isolated"
+     */
+    updateLeverage(symbol: string, leverage: number, leverageType?: "cross" | "isolated"): Promise<any>;
+    /**
+     * Place one or more perpetual orders.
+     * @param orders - Array of order objects (see docs for BaseOrderParams)
+     */
+    placeOrder(orders: any[]): Promise<PerpsOrderResponse>;
+    /**
+     * Cancel one or more open orders.
+     * @param cancels - Array of { assetIndex, oid }
+     */
+    cancelOrders(cancels: {
+        assetIndex: number;
+        oid: number;
+    }[]): Promise<any>;
+    /**
+     * Modify an existing order.
+     * @param oid - Order ID to modify
+     * @param order - New order parameters
+     */
+    modifyOrder(oid: number, order: any): Promise<any>;
+    /**
+     * Close a position (convenience — creates reduce-only IOC with 10% slippage).
+     * @param symbol - Market symbol
+     * @param positionSide - "long" or "short"
+     * @param size - Position size to close
+     * @param currentPrice - Current market price
+     * @param closePercent - Percentage to close (default: 100)
+     */
+    closePosition(symbol: string, positionSide: "long" | "short", size: number, currentPrice: number, closePercent?: number): Promise<any>;
+    /** Get open orders */
+    getOrders(): Promise<any>;
+    /** Get trade execution history */
+    getTradeExecutions(): Promise<any>;
+    /**
+     * Get positions and margin summary (queries Hyperliquid directly).
+     * @param wallet - Your Hyperliquid wallet address (from getWalletAddress)
+     */
+    getPositions(wallet: string): Promise<PerpsPositionsResponse>;
+    /**
+     * Get open orders from Hyperliquid directly.
+     * @param wallet - Your Hyperliquid wallet address
+     */
+    getOpenOrders(wallet: string): Promise<any>;
+}
+
+declare class BridgeModule {
+    private http;
+    private auth;
+    constructor(http: HttpClient, auth: () => Promise<void>);
+    /**
+     * Get all supported chains for cross-chain bridging.
+     */
+    getChains(): Promise<BridgeChainsResponse>;
+    /**
+     * Get tokens available on specified chains.
+     * @param chains - Comma-separated chain IDs (e.g. "43114,42161")
+     */
+    getTokens(chains: string): Promise<BridgeTokensResponse>;
+    /**
+     * Get info for a specific token on a chain.
+     * @param chainId - Chain ID
+     * @param address - Token contract address
+     */
+    getToken(chainId: number, address: string): Promise<BridgeTokenResponse>;
+    /**
+     * Get available bridge connections between two chains.
+     * @param fromChainId - Source chain ID
+     * @param toChainId - Destination chain ID
+     * @param fromToken - Optional source token address
+     * @param toToken - Optional destination token address
+     */
+    getConnections(fromChainId: number, toChainId: number, fromToken?: string, toToken?: string): Promise<BridgeConnectionsResponse>;
+    /**
+     * Get a bridge quote with unsigned transaction data.
+     * The agent signs the returned tx on the source chain.
+     *
+     * @param fromChainId - Source chain ID
+     * @param toChainId - Destination chain ID
+     * @param fromToken - Source token address (use 0x0000...0000 for native tokens)
+     * @param toToken - Destination token address
+     * @param fromAmount - Human-readable amount (e.g. "0.1")
+     * @param fromAddress - Sender wallet address
+     * @param toAddress - Optional receiver address (defaults to fromAddress)
+     * @param slippage - Slippage tolerance as decimal (default 0.03 = 3%)
+     * @param fromDecimals - Token decimals (default 18)
+     */
+    getQuote(fromChainId: number, toChainId: number, fromToken: string, toToken: string, fromAmount: string, fromAddress: string, toAddress?: string, slippage?: number, fromDecimals?: number): Promise<BridgeQuoteResponse>;
+    /**
+     * Get multiple bridge route options.
+     */
+    getRoutes(fromChainId: number, toChainId: number, fromToken: string, toToken: string, fromAmount: string, fromAddress: string, toAddress?: string, slippage?: number, fromDecimals?: number): Promise<BridgeRoutesResponse>;
+    /**
+     * Check bridge transfer status.
+     * @param txHash - Source chain transaction hash
+     * @param fromChainId - Source chain ID
+     * @param toChainId - Destination chain ID
+     * @param bridge - Optional bridge tool name
+     */
+    getStatus(txHash: string, fromChainId: number, toChainId: number, bridge?: string): Promise<BridgeStatusResponse>;
+    /**
+     * Get reference info — common chain IDs, USDC addresses, native token constant.
+     */
+    getInfo(): Promise<BridgeInfoResponse>;
+}
+
 interface LogiqicalConfig {
     /** Your wallet address — used for auto-registration */
     wallet: string;
@@ -507,8 +817,12 @@ declare class LogiqicalClient {
     readonly staking: StakingModule;
     /** Discover, research, and trade launchpad tokens on bonding curves */
     readonly launchpad: LaunchpadModule;
-    /** Swap any Avalanche token via LFJ + Pharaoh DEX */
+    /** Swap any Avalanche token via LFJ + Arena DEX */
     readonly dex: DexModule;
+    /** Trade perpetual futures on Hyperliquid via Arena */
+    readonly perps: PerpsModule;
+    /** Cross-chain token bridging via Li.Fi — any token, any chain */
+    readonly bridge: BridgeModule;
     private http;
     private wallet;
     private agentName;
@@ -549,4 +863,4 @@ declare class LogiqicalAuthError extends LogiqicalError {
     constructor(endpoint: string);
 }
 
-export { type BalancesResponse, type BroadcastResponse, type BuyQuoteResponse, type DexBalanceResponse, DexModule, type DexQuoteResponse, type DexSwapResponse, type DexTokenEntry, type DexTokenInfoResponse, type DexTokensResponse, type GlobalTradeEntry, type GlobalTradesResponse, type HealthResponse, type HolderEntry, type LaunchpadBuyResponse, type LaunchpadListResponse, LaunchpadModule, type LaunchpadQuoteResponse, type LaunchpadSellResponse, type LaunchpadToken, LogiqicalAuthError, LogiqicalClient, type LogiqicalConfig, LogiqicalError, type RegisterResponse, type SellQuoteResponse, type StakeBuildResponse, type StakeInfoResponse, StakingModule, type SwapBuyResponse, SwapModule, type SwapSellResponse, type TokenActivityResponse, type TokenCreator, type TokenDetailResponse, type TokenHoldersResponse, type TokenStatsTimeframes, type TradeEntry, type UnsignedTx };
+export { type ArenaCommunity, type BalancesResponse, type BridgeChainsResponse, type BridgeConnectionsResponse, type BridgeInfoResponse, type BridgeLiFiChain, type BridgeLiFiToken, BridgeModule, type BridgeQuoteResponse, type BridgeRoutesResponse, type BridgeStatusResponse, type BridgeTokenResponse, type BridgeTokensResponse, type BridgeTransaction, type BroadcastResponse, type BuildCreateResponse, type BuyQuoteResponse, type DexBalanceResponse, DexModule, type DexQuoteResponse, type DexSwapResponse, type DexTokenEntry, type DexTokenInfoResponse, type DexTokensResponse, type GlobalTradeEntry, type GlobalTradesResponse, type HealthResponse, type HolderEntry, type LaunchTokenResponse, type LaunchpadBuyResponse, type LaunchpadListResponse, LaunchpadModule, type LaunchpadQuoteResponse, type LaunchpadSellResponse, type LaunchpadToken, LogiqicalAuthError, LogiqicalClient, type LogiqicalConfig, LogiqicalError, PerpsModule, type PerpsOrderResponse, type PerpsPositionsResponse, type PerpsSetupResponse, type PerpsTradingPair, type PerpsTradingPairsResponse, type RegisterResponse, type SellQuoteResponse, type StakeBuildResponse, type StakeInfoResponse, StakingModule, type SwapBuyResponse, SwapModule, type SwapSellResponse, type TokenActivityResponse, type TokenCreator, type TokenDetailResponse, type TokenHoldersResponse, type TokenStatsTimeframes, type TradeEntry, type UnsignedTx, type UploadImageResponse };