logiqical 0.1.0

package/dist/index.mjs

@@ -0,0 +1,475 @@
+// src/errors.ts
+var LogiqicalError = class extends Error {
+  constructor(message, statusCode, endpoint) {
+    super(message);
+    this.statusCode = statusCode;
+    this.endpoint = endpoint;
+    this.name = "LogiqicalError";
+  }
+};
+var LogiqicalAuthError = class extends LogiqicalError {
+  constructor(endpoint) {
+    super("Invalid or missing API key. Call client.register() or provide an apiKey in config.", 401, endpoint);
+    this.name = "LogiqicalAuthError";
+  }
+};
+
+// src/http.ts
+var HttpClient = class {
+  constructor(baseUrl, apiKey) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey ?? null;
+  }
+  apiKey;
+  setApiKey(key) {
+    this.apiKey = key;
+  }
+  getApiKey() {
+    return this.apiKey;
+  }
+  async get(path, params, skipAuth = false) {
+    const url = new URL(path, this.baseUrl);
+    if (params) {
+      for (const [k, v] of Object.entries(params)) {
+        if (v !== void 0) url.searchParams.set(k, String(v));
+      }
+    }
+    const headers = {};
+    if (!skipAuth && this.apiKey) headers["X-API-Key"] = this.apiKey;
+    const res = await fetch(url.toString(), { headers });
+    return this.handleResponse(res, path);
+  }
+  async post(path, body) {
+    const url = new URL(path, this.baseUrl);
+    const headers = { "Content-Type": "application/json" };
+    if (this.apiKey) headers["X-API-Key"] = this.apiKey;
+    const res = await fetch(url.toString(), { method: "POST", headers, body: JSON.stringify(body) });
+    return this.handleResponse(res, path);
+  }
+  async handleResponse(res, endpoint) {
+    if (res.status === 401) throw new LogiqicalAuthError(endpoint);
+    const data = await res.json().catch(() => null);
+    if (!res.ok) {
+      const msg = data?.error ?? `HTTP ${res.status}`;
+      throw new LogiqicalError(msg, res.status, endpoint);
+    }
+    return data;
+  }
+};
+
+// src/modules/swap.ts
+var SwapModule = class {
+  constructor(http, auth) {
+    this.http = http;
+    this.auth = auth;
+  }
+  /**
+   * Get AVAX and ARENA token balances for a wallet.
+   * @param wallet - Wallet address to check
+   */
+  async getBalances(wallet) {
+    await this.auth();
+    return this.http.get("/balances", { wallet });
+  }
+  /**
+   * Quote how much ARENA you get for a given amount of AVAX.
+   * @param avax - Amount of AVAX to spend
+   */
+  async quote(avax) {
+    await this.auth();
+    return this.http.get("/quote", { avax });
+  }
+  /**
+   * Quote how much AVAX you get for selling a given amount of ARENA.
+   * @param arena - Amount of ARENA to sell
+   */
+  async sellQuote(arena) {
+    await this.auth();
+    return this.http.get("/quote/sell", { arena });
+  }
+  /**
+   * 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%)
+   */
+  async buildBuy(wallet, avax, slippage) {
+    await this.auth();
+    return this.http.get("/build/buy", { wallet, avax, slippage });
+  }
+  /**
+   * 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%)
+   */
+  async buildSell(wallet, amount, slippage) {
+    await this.auth();
+    return this.http.get("/build/sell-arena", { wallet, amount, slippage });
+  }
+};
+
+// src/modules/staking.ts
+var StakingModule = class {
+  constructor(http, auth) {
+    this.http = http;
+    this.auth = auth;
+  }
+  /**
+   * Get staking info for a wallet — staked amount, pending rewards, APY.
+   * @param wallet - Wallet address to check
+   */
+  async getInfo(wallet) {
+    await this.auth();
+    return this.http.get("/stake/info", { wallet });
+  }
+  /**
+   * 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
+   */
+  async buildStake(wallet, amount) {
+    await this.auth();
+    return this.http.get("/build/stake", { wallet, amount });
+  }
+  /**
+   * 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%)
+   */
+  async buildBuyAndStake(wallet, avax, slippage) {
+    await this.auth();
+    return this.http.get("/build/buy-and-stake", { wallet, avax, slippage });
+  }
+  /**
+   * Build unsigned transaction to unstake ARENA tokens and claim rewards.
+   * @param wallet - Your wallet address
+   * @param amount - Amount of ARENA to unstake
+   */
+  async buildUnstake(wallet, amount) {
+    await this.auth();
+    return this.http.get("/build/unstake", { wallet, amount });
+  }
+};
+
+// src/modules/launchpad.ts
+var LaunchpadModule = class {
+  constructor(http, auth) {
+    this.http = http;
+    this.auth = auth;
+  }
+  // ── Discovery ──
+  /**
+   * 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)
+   */
+  async getRecent(count, type) {
+    await this.auth();
+    return this.http.get("/launchpad/recent", { count, type });
+  }
+  /**
+   * Search for a token by name, symbol, or contract address.
+   * @param q - Search query — name, symbol, or 0x contract address
+   */
+  async search(q) {
+    await this.auth();
+    return this.http.get("/launchpad/search", { q });
+  }
+  /**
+   * Get tokens that are closest to graduating from the bonding curve to DEX.
+   * @param count - Number of tokens (max 20, default 5)
+   */
+  async getGraduating(count) {
+    await this.auth();
+    return this.http.get("/launchpad/graduating", { count });
+  }
+  /**
+   * Get tokens that have already graduated from the bonding curve to DEX.
+   * @param count - Number of tokens (max 50, default 10)
+   */
+  async getGraduated(count) {
+    await this.auth();
+    return this.http.get("/launchpad/graduated", { count });
+  }
+  /**
+   * Get top tokens by trading volume.
+   * @param timeframe - "5m", "1h", "4h", "24h", or "all_time"
+   * @param count - Number of tokens (max 50, default 10)
+   */
+  async getTopVolume(timeframe, count) {
+    await this.auth();
+    return this.http.get("/launchpad/top-volume", { timeframe, count });
+  }
+  // ── Intelligence ──
+  /**
+   * 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...)
+   */
+  async getToken(tokenId, address) {
+    await this.auth();
+    return this.http.get("/launchpad/token", { tokenId, address });
+  }
+  /**
+   * 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.
+   */
+  async quote(tokenId, side, amount) {
+    await this.auth();
+    const params = { tokenId, side };
+    if (side === "buy") params.avax = amount;
+    else params.tokenAmount = amount;
+    return this.http.get("/launchpad/quote", params);
+  }
+  /**
+   * Get agent's tracked portfolio — all launchpad tokens the agent has bought.
+   * @param wallet - Agent wallet address
+   */
+  async getPortfolio(wallet) {
+    await this.auth();
+    return this.http.get("/launchpad/portfolio", { wallet });
+  }
+  /**
+   * Get market cap data for a token.
+   * @param tokenId - Arena token ID
+   */
+  async getMarketCap(tokenId) {
+    await this.auth();
+    return this.http.get("/launchpad/market-cap", { tokenId });
+  }
+  /**
+   * 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)
+   */
+  async getActivity(tokenId, address, count) {
+    await this.auth();
+    return this.http.get("/launchpad/activity", { tokenId, address, count });
+  }
+  /**
+   * 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)
+   */
+  async getHolders(address, tokenId, count) {
+    await this.auth();
+    return this.http.get("/launchpad/holders", { address, tokenId, count });
+  }
+  /**
+   * Get platform overview — total tokens launched, contract addresses, stats.
+   */
+  async getOverview() {
+    await this.auth();
+    return this.http.get("/launchpad/overview");
+  }
+  /**
+   * Get the global trade feed across all launchpad tokens.
+   * @param count - Number of trades (max 100, default 50)
+   * @param offset - Pagination offset
+   */
+  async getTrades(count, offset) {
+    await this.auth();
+    return this.http.get("/launchpad/trades", { count, offset });
+  }
+  // ── Trading ──
+  /**
+   * 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%)
+   */
+  async buildBuy(wallet, tokenId, avax, slippage) {
+    await this.auth();
+    return this.http.get("/launchpad/build/buy", { wallet, tokenId, avax, slippage });
+  }
+  /**
+   * 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%)
+   */
+  async buildSell(wallet, tokenId, amount, slippage) {
+    await this.auth();
+    return this.http.get("/launchpad/build/sell", { wallet, tokenId, amount, slippage });
+  }
+};
+
+// src/modules/dex.ts
+var DexModule = class {
+  constructor(http, auth) {
+    this.http = http;
+    this.auth = auth;
+  }
+  /**
+   * List all known tokens with addresses and decimals.
+   * You can also pass any contract address directly to other methods — not limited to this list.
+   */
+  async getTokens() {
+    await this.auth();
+    return this.http.get("/dex/tokens");
+  }
+  /**
+   * Get on-chain info for any token by contract address — name, symbol, decimals.
+   * @param address - Token contract address (0x...)
+   */
+  async getTokenInfo(address) {
+    await this.auth();
+    return this.http.get("/dex/token-info", { address });
+  }
+  /**
+   * 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
+   */
+  async quote(from, to, amount) {
+    await this.auth();
+    return this.http.get("/dex/quote", { from, to, amount });
+  }
+  /**
+   * Get the balance of any token for a wallet.
+   * @param wallet - Wallet address
+   * @param token - Token symbol or contract address
+   */
+  async getBalance(wallet, token) {
+    await this.auth();
+    return this.http.get("/dex/balance", { wallet, token });
+  }
+  /**
+   * 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%)
+   */
+  async buildSwap(wallet, from, to, amount, slippage) {
+    await this.auth();
+    return this.http.get("/dex/build/swap", { wallet, from, to, amount, slippage });
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://brave-alignment-production-1706.up.railway.app";
+var LogiqicalClient = class {
+  /** Buy/sell ARENA tokens via LFJ DEX */
+  swap;
+  /** Stake ARENA tokens for rewards */
+  staking;
+  /** Discover, research, and trade launchpad tokens on bonding curves */
+  launchpad;
+  /** Swap any Avalanche token via LFJ + Pharaoh DEX */
+  dex;
+  http;
+  wallet;
+  agentName;
+  registrationPromise = null;
+  constructor(config) {
+    this.wallet = config.wallet;
+    this.agentName = config.name ?? "agent";
+    this.http = new HttpClient(config.baseUrl ?? DEFAULT_BASE_URL, config.apiKey);
+    const auth = () => this.ensureRegistered();
+    this.swap = new SwapModule(this.http, auth);
+    this.staking = new StakingModule(this.http, auth);
+    this.launchpad = new LaunchpadModule(this.http, auth);
+    this.dex = new DexModule(this.http, auth);
+  }
+  /** The API key (available after first call or if provided in config) */
+  get apiKey() {
+    return this.http.getApiKey();
+  }
+  /**
+   * Broadcast a signed transaction to the Avalanche network.
+   * @param signedTx - Signed transaction hex string
+   * @returns Transaction hash
+   */
+  async broadcast(signedTx) {
+    await this.ensureRegistered();
+    return this.http.post("/broadcast", { signedTx });
+  }
+  /**
+   * Get the full agent instructions document — describes all available capabilities.
+   */
+  async getInstructions() {
+    await this.ensureRegistered();
+    return this.http.get("/agent-instructions");
+  }
+  /**
+   * Check if the API is healthy and responsive.
+   */
+  async health() {
+    return this.http.get("/health", void 0, true);
+  }
+  /**
+   * Manually register and get an API key.
+   * Usually not needed — the client auto-registers on first call.
+   */
+  async register() {
+    const data = await this.http.get("/register", {
+      wallet: this.wallet,
+      name: this.agentName
+    }, true);
+    const apiKey = data.apiKey || data.key;
+    this.http.setApiKey(apiKey);
+    return { apiKey, wallet: data.wallet, name: data.name };
+  }
+  async ensureRegistered() {
+    if (this.http.getApiKey()) return;
+    if (!this.registrationPromise) {
+      this.registrationPromise = this.register().then(() => {
+      }).catch((e) => {
+        this.registrationPromise = null;
+        throw e;
+      });
+    }
+    return this.registrationPromise;
+  }
+};
+export {
+  DexModule,
+  LaunchpadModule,
+  LogiqicalAuthError,
+  LogiqicalClient,
+  LogiqicalError,
+  StakingModule,
+  SwapModule
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "logiqical",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for AI agents to trade on Avalanche — swaps, staking, launchpad, DEX",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["avalanche", "arena", "defi", "sdk", "ai-agent", "trading", "logiqical"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OlaCryto/arena-agent-plugin.git",
+    "directory": "sdk"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  }
+}