logiqical 0.0.9

package/README.md

@@ -0,0 +1,129 @@
+# logiqical
+
+The complete SDK for AI agents trading on Avalanche. Swaps, staking, launchpad, 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");
+
+// 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
+
+| 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 |
+| `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 |
+| `buildBuy(wallet, tokenId, avax, slippage?)` | Buy launchpad token |
+| `buildSell(wallet, tokenId, amount, slippage?)` | Sell (`"max"` for all) |
+
+### `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 |
+
+## 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`
+- **30+ methods** across 4 modules
+
+## Built on
+
+- [Avalanche C-Chain](https://avax.network)
+- [LFJ DEX](https://lfj.gg)
+- [Pharaoh DEX](https://pharaoh.exchange)
+- [Arena](https://arenatrade.ai)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,552 @@
+declare class HttpClient {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey?: string);
+    setApiKey(key: string): void;
+    getApiKey(): string | null;
+    get<T>(path: string, params?: Record<string, string | number | undefined>, skipAuth?: boolean): Promise<T>;
+    post<T>(path: string, body: Record<string, unknown>): Promise<T>;
+    private handleResponse;
+}
+
+/** Unsigned transaction ready to be signed and broadcast */
+interface UnsignedTx {
+    to: string;
+    data: string;
+    value: string;
+    chainId: number;
+    gas?: string;
+    gasLimit?: string;
+    description?: string;
+}
+interface BalancesResponse {
+    wallet: string;
+    avax: string;
+    arena: string;
+    avaxFormatted: string;
+    arenaFormatted: string;
+}
+interface BuyQuoteResponse {
+    avaxIn: string;
+    arenaOut: string;
+    arenaOutFormatted: string;
+    rate: string;
+    priceImpact: string;
+}
+interface SellQuoteResponse {
+    arenaIn: string;
+    avaxOut: string;
+    avaxOutFormatted: string;
+    rate: string;
+    priceImpact: string;
+}
+interface SwapBuyResponse {
+    transactions: UnsignedTx[];
+    summary: string;
+}
+interface SwapSellResponse {
+    transactions: UnsignedTx[];
+}
+interface StakeInfoResponse {
+    staked: string;
+    stakedFormatted: string;
+    rewards: string;
+    rewardsFormatted: string;
+    apy: string;
+}
+interface StakeBuildResponse {
+    transactions: UnsignedTx[];
+}
+interface TokenCreator {
+    address: string;
+    handle: string;
+    photoUrl: string;
+    twitterFollowers: number | null;
+    totalTokensCreated: number | null;
+}
+interface LaunchpadToken {
+    tokenId: string;
+    type: "AVAX-paired" | "ARENA-paired";
+    name: string;
+    symbol: string;
+    tokenAddress: string;
+    photoUrl: string;
+    description: string | null;
+    creator: TokenCreator;
+    price: {
+        eth: number;
+        usd: number;
+        avaxPrice: number;
+    };
+    volume: {
+        totalEth: number;
+        totalUsd: number;
+    };
+    holders: number;
+    transactions: number;
+    graduationProgress: string | null;
+    graduated: boolean;
+    supply: number;
+    createdAt: string | null;
+    whitelist: unknown;
+    isOfficial: boolean;
+    dexPoolId: string | null;
+}
+interface LaunchpadListResponse {
+    count: number;
+    tokens: LaunchpadToken[];
+}
+interface TokenStatsTimeframes {
+    "5m": number;
+    "1h": number;
+    "4h": number;
+    "12h": number;
+    "24h": number;
+}
+interface TokenDetailResponse extends LaunchpadToken {
+    stats?: {
+        buys: TokenStatsTimeframes;
+        sells: TokenStatsTimeframes;
+        uniqueBuyers: TokenStatsTimeframes;
+        uniqueSellers: TokenStatsTimeframes;
+        volume: TokenStatsTimeframes;
+        priceChange: TokenStatsTimeframes;
+    };
+}
+interface LaunchpadQuoteResponse {
+    tokensOut?: string;
+    avaxCost?: string;
+    avaxOut?: string;
+    fees?: Record<string, string>;
+}
+interface TradeEntry {
+    type: "buy" | "sell";
+    trader: {
+        address: string;
+        handle: string;
+        name: string;
+        photoUrl: string;
+        twitterFollowers: number | null;
+    };
+    tokenAmount: number;
+    costOrReward?: {
+        eth: number;
+        usd: number;
+    };
+    value?: {
+        eth: number;
+        usd: number;
+    };
+    priceEth: number;
+    txHash: string;
+    time: string | null;
+}
+interface TokenActivityResponse {
+    tokenId: string | null;
+    tokenAddress: string;
+    trades: TradeEntry[];
+}
+interface HolderEntry {
+    rank: number;
+    address: string;
+    handle: string;
+    name: string;
+    photoUrl: string;
+    twitterFollowers: number | null;
+    balance: number;
+    unrealizedPnl: {
+        eth: number;
+        usd: number;
+    };
+    realizedPnl: {
+        eth: number;
+        usd: number;
+    };
+    buys: number;
+    sells: number;
+}
+interface TokenHoldersResponse {
+    tokenAddress: string;
+    holders: HolderEntry[];
+}
+interface GlobalTradeEntry extends TradeEntry {
+    token: {
+        name: string;
+        symbol: string;
+        address: string;
+        photoUrl: string;
+        tokenId: string;
+    };
+}
+interface GlobalTradesResponse {
+    count: number;
+    offset: number;
+    trades: GlobalTradeEntry[];
+}
+interface LaunchpadBuyResponse {
+    transactions?: UnsignedTx[];
+    graduated?: boolean;
+    summary?: string;
+    note?: string;
+}
+interface LaunchpadSellResponse {
+    transactions: UnsignedTx[];
+    graduated?: boolean;
+    summary?: string;
+    note?: string;
+}
+interface DexTokenEntry {
+    symbol: string;
+    address: string;
+    decimals: number;
+}
+interface DexTokensResponse {
+    tokens: DexTokenEntry[];
+    note: string;
+}
+interface DexTokenInfoResponse {
+    address: string;
+    symbol: string;
+    name: string;
+    decimals: number;
+}
+interface DexQuoteResponse {
+    from: string;
+    to: string;
+    amountIn: string;
+    amountOut: string;
+    rate: string;
+    priceImpact: string;
+    path: string[];
+}
+interface DexBalanceResponse {
+    wallet: string;
+    token: string;
+    balance: string;
+    formatted: string;
+    symbol: string;
+}
+interface DexSwapResponse {
+    transactions: UnsignedTx[];
+    summary: string;
+}
+interface RegisterResponse {
+    apiKey: string;
+    wallet: string;
+    name: string;
+}
+interface BroadcastResponse {
+    txHash: string;
+}
+interface HealthResponse {
+    status: string;
+    router: string;
+    fee: string;
+}
+
+declare class SwapModule {
+    private http;
+    private auth;
+    constructor(http: HttpClient, auth: () => Promise<void>);
+    /**
+     * Get AVAX and ARENA token balances for a wallet.
+     * @param wallet - Wallet address to check
+     */
+    getBalances(wallet: string): Promise<BalancesResponse>;
+    /**
+     * Quote how much ARENA you get for a given amount of AVAX.
+     * @param avax - Amount of AVAX to spend
+     */
+    quote(avax: string): Promise<BuyQuoteResponse>;
+    /**
+     * Quote how much AVAX you get for selling a given amount of ARENA.
+     * @param arena - Amount of ARENA to sell
+     */
+    sellQuote(arena: string): Promise<SellQuoteResponse>;
+    /**
+     * Build unsigned transaction to buy ARENA with AVAX.
+     *
+     * Sign the transaction, then broadcast via `client.broadcast()`.
+     *
+     * @param wallet - Your wallet address
+     * @param avax - Amount of AVAX to spend
+     * @param slippage - Slippage tolerance in basis points (default: 500 = 5%)
+     */
+    buildBuy(wallet: string, avax: string, slippage?: number): Promise<SwapBuyResponse>;
+    /**
+     * Build unsigned transactions to sell ARENA for AVAX.
+     *
+     * Returns 2 transactions — execute in order:
+     * 1. Approve — allows the DEX router to spend your ARENA
+     * 2. Swap — executes the ARENA → AVAX swap
+     *
+     * Sign each, broadcast via `client.broadcast()`, wait for confirmation before the next.
+     *
+     * @param wallet - Your wallet address
+     * @param amount - Amount of ARENA to sell, or "max" for entire balance
+     * @param slippage - Slippage tolerance in basis points (default: 500 = 5%)
+     */
+    buildSell(wallet: string, amount: string, slippage?: number): Promise<SwapSellResponse>;
+}
+
+declare class StakingModule {
+    private http;
+    private auth;
+    constructor(http: HttpClient, auth: () => Promise<void>);
+    /**
+     * Get staking info for a wallet — staked amount, pending rewards, APY.
+     * @param wallet - Wallet address to check
+     */
+    getInfo(wallet: string): Promise<StakeInfoResponse>;
+    /**
+     * Build unsigned transactions to stake ARENA tokens.
+     *
+     * Returns 2 transactions — execute in order:
+     * 1. Approve — allows the staking contract to spend your ARENA
+     * 2. Stake — deposits ARENA into staking
+     *
+     * @param wallet - Your wallet address
+     * @param amount - Amount of ARENA to stake
+     */
+    buildStake(wallet: string, amount: string): Promise<StakeBuildResponse>;
+    /**
+     * Build unsigned transactions to buy ARENA with AVAX and stake in one flow.
+     *
+     * Combines swap + approve + stake. Returns multiple transactions — execute in order.
+     *
+     * @param wallet - Your wallet address
+     * @param avax - Amount of AVAX to spend
+     * @param slippage - Slippage tolerance in basis points (default: 500 = 5%)
+     */
+    buildBuyAndStake(wallet: string, avax: string, slippage?: number): Promise<StakeBuildResponse>;
+    /**
+     * Build unsigned transaction to unstake ARENA tokens and claim rewards.
+     * @param wallet - Your wallet address
+     * @param amount - Amount of ARENA to unstake
+     */
+    buildUnstake(wallet: string, amount: string): Promise<UnsignedTx>;
+}
+
+declare class LaunchpadModule {
+    private http;
+    private auth;
+    constructor(http: HttpClient, auth: () => Promise<void>);
+    /**
+     * Get recently launched tokens on Arena.
+     * @param count - Number of tokens (max 50, default 10)
+     * @param type - Filter: "all", "avax" (AVAX-paired), or "arena" (ARENA-paired)
+     */
+    getRecent(count?: number, type?: "all" | "avax" | "arena"): Promise<LaunchpadListResponse>;
+    /**
+     * Search for a token by name, symbol, or contract address.
+     * @param q - Search query — name, symbol, or 0x contract address
+     */
+    search(q: string): Promise<LaunchpadListResponse | LaunchpadToken>;
+    /**
+     * Get tokens that are closest to graduating from the bonding curve to DEX.
+     * @param count - Number of tokens (max 20, default 5)
+     */
+    getGraduating(count?: number): Promise<LaunchpadListResponse>;
+    /**
+     * Get tokens that have already graduated from the bonding curve to DEX.
+     * @param count - Number of tokens (max 50, default 10)
+     */
+    getGraduated(count?: number): Promise<LaunchpadListResponse>;
+    /**
+     * Get top tokens by trading volume.
+     * @param timeframe - "5m", "1h", "4h", "24h", or "all_time"
+     * @param count - Number of tokens (max 50, default 10)
+     */
+    getTopVolume(timeframe?: "5m" | "1h" | "4h" | "24h" | "all_time", count?: number): Promise<LaunchpadListResponse & {
+        timeframe: string;
+    }>;
+    /**
+     * Get full token profile with stats — price, market cap, graduation progress, buy/sell activity.
+     * @param tokenId - Arena token ID
+     * @param address - Or token contract address (0x...)
+     */
+    getToken(tokenId?: string, address?: string): Promise<TokenDetailResponse>;
+    /**
+     * Get a buy or sell quote for a bonding curve token.
+     * @param tokenId - Arena token ID
+     * @param side - "buy" or "sell"
+     * @param amount - For buy: AVAX amount. For sell: token amount.
+     */
+    quote(tokenId: string, side: "buy" | "sell", amount: string): Promise<LaunchpadQuoteResponse>;
+    /**
+     * Get agent's tracked portfolio — all launchpad tokens the agent has bought.
+     * @param wallet - Agent wallet address
+     */
+    getPortfolio(wallet: string): Promise<unknown>;
+    /**
+     * Get market cap data for a token.
+     * @param tokenId - Arena token ID
+     */
+    getMarketCap(tokenId: string): Promise<unknown>;
+    /**
+     * Get recent trade activity for a token.
+     * @param tokenId - Arena token ID
+     * @param address - Or token contract address
+     * @param count - Number of trades (max 50, default 20)
+     */
+    getActivity(tokenId?: string, address?: string, count?: number): Promise<TokenActivityResponse>;
+    /**
+     * Get top holders for a token with PnL data.
+     * @param address - Token contract address
+     * @param tokenId - Or Arena token ID
+     * @param count - Number of holders (max 50, default 20)
+     */
+    getHolders(address?: string, tokenId?: string, count?: number): Promise<TokenHoldersResponse>;
+    /**
+     * Get platform overview — total tokens launched, contract addresses, stats.
+     */
+    getOverview(): Promise<unknown>;
+    /**
+     * Get the global trade feed across all launchpad tokens.
+     * @param count - Number of trades (max 100, default 50)
+     * @param offset - Pagination offset
+     */
+    getTrades(count?: number, offset?: number): Promise<GlobalTradesResponse>;
+    /**
+     * Build unsigned transaction to buy a launchpad token with AVAX.
+     *
+     * Auto-detects if the token is AVAX-paired or ARENA-paired and routes accordingly.
+     * If the token has graduated to DEX, returns transactions for DEX swap instead.
+     *
+     * @param wallet - Your wallet address
+     * @param tokenId - Arena token ID
+     * @param avax - Amount of AVAX to spend
+     * @param slippage - Slippage in basis points (default: 500 = 5%)
+     */
+    buildBuy(wallet: string, tokenId: string, avax: string, slippage?: number): Promise<LaunchpadBuyResponse>;
+    /**
+     * Build unsigned transaction(s) to sell a launchpad token.
+     *
+     * Returns approve + sell transactions. Execute in order.
+     * Use amount="max" to sell entire balance.
+     *
+     * If the token has graduated to DEX, returns transactions for DEX swap instead.
+     *
+     * @param wallet - Your wallet address
+     * @param tokenId - Arena token ID
+     * @param amount - Token amount to sell, or "max" for entire balance
+     * @param slippage - Slippage in basis points (default: 500 = 5%)
+     */
+    buildSell(wallet: string, tokenId: string, amount: string, slippage?: number): Promise<LaunchpadSellResponse>;
+}
+
+declare class DexModule {
+    private http;
+    private auth;
+    constructor(http: HttpClient, auth: () => Promise<void>);
+    /**
+     * List all known tokens with addresses and decimals.
+     * You can also pass any contract address directly to other methods — not limited to this list.
+     */
+    getTokens(): Promise<DexTokensResponse>;
+    /**
+     * Get on-chain info for any token by contract address — name, symbol, decimals.
+     * @param address - Token contract address (0x...)
+     */
+    getTokenInfo(address: string): Promise<DexTokenInfoResponse>;
+    /**
+     * Quote a swap between any two tokens on Avalanche.
+     * @param from - Source token symbol or contract address
+     * @param to - Destination token symbol or contract address
+     * @param amount - Amount of source token to swap
+     */
+    quote(from: string, to: string, amount: string): Promise<DexQuoteResponse>;
+    /**
+     * Get the balance of any token for a wallet.
+     * @param wallet - Wallet address
+     * @param token - Token symbol or contract address
+     */
+    getBalance(wallet: string, token: string): Promise<DexBalanceResponse>;
+    /**
+     * Build unsigned transaction(s) to swap any token pair on Avalanche via LFJ/Pharaoh DEX.
+     *
+     * May return multiple transactions (approve + swap). Execute in order.
+     *
+     * @param wallet - Your wallet address
+     * @param from - Source token symbol or contract address
+     * @param to - Destination token symbol or contract address
+     * @param amount - Amount to swap, or "max" for entire balance
+     * @param slippage - Slippage tolerance in basis points (default: 500 = 5%)
+     */
+    buildSwap(wallet: string, from: string, to: string, amount: string, slippage?: number): Promise<DexSwapResponse>;
+}
+
+interface LogiqicalConfig {
+    /** Your wallet address — used for auto-registration */
+    wallet: string;
+    /** Existing API key (skips auto-registration if provided) */
+    apiKey?: string;
+    /** Custom base URL (defaults to Logiqical production API) */
+    baseUrl?: string;
+    /** Agent display name for registration */
+    name?: string;
+}
+/**
+ * Logiqical SDK client — the complete toolkit for AI agents trading on Avalanche.
+ *
+ * ```ts
+ * import { LogiqicalClient } from "logiqical";
+ *
+ * const client = new LogiqicalClient({ wallet: "0xYourWallet" });
+ *
+ * // Auto-registers on first call — no setup needed
+ * const balances = await client.swap.getBalances("0xYourWallet");
+ * const tokens = await client.launchpad.getRecent(10);
+ * const tx = await client.dex.buildSwap("0xWallet", "AVAX", "USDC", "1.0");
+ * ```
+ */
+declare class LogiqicalClient {
+    /** Buy/sell ARENA tokens via LFJ DEX */
+    readonly swap: SwapModule;
+    /** Stake ARENA tokens for rewards */
+    readonly staking: StakingModule;
+    /** Discover, research, and trade launchpad tokens on bonding curves */
+    readonly launchpad: LaunchpadModule;
+    /** Swap any Avalanche token via LFJ + Pharaoh DEX */
+    readonly dex: DexModule;
+    private http;
+    private wallet;
+    private agentName;
+    private registrationPromise;
+    constructor(config: LogiqicalConfig);
+    /** The API key (available after first call or if provided in config) */
+    get apiKey(): string | null;
+    /**
+     * Broadcast a signed transaction to the Avalanche network.
+     * @param signedTx - Signed transaction hex string
+     * @returns Transaction hash
+     */
+    broadcast(signedTx: string): Promise<BroadcastResponse>;
+    /**
+     * Get the full agent instructions document — describes all available capabilities.
+     */
+    getInstructions(): Promise<string>;
+    /**
+     * Check if the API is healthy and responsive.
+     */
+    health(): Promise<HealthResponse>;
+    /**
+     * Manually register and get an API key.
+     * Usually not needed — the client auto-registers on first call.
+     */
+    register(): Promise<RegisterResponse>;
+    private ensureRegistered;
+}
+
+/** Error returned by the Logiqical API */
+declare class LogiqicalError extends Error {
+    readonly statusCode: number;
+    readonly endpoint: string;
+    constructor(message: string, statusCode: number, endpoint: string);
+}
+/** Authentication error — invalid or missing API key */
+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 };