suprafx-agent-sdk 0.3.1

package/dist/bin/suprafx-mcp.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+/**
+ * `suprafx-mcp` CLI entry point.
+ *
+ * Two modes:
+ *   - `suprafx-mcp init` — interactive setup wizard. Writes
+ *     `~/.suprafx/config.json` with the user's delegate priv key
+ *     after they paste it in or point to a JSON file the dApp
+ *     downloaded.
+ *   - `suprafx-mcp` (no args) — runs the MCP server over stdio.
+ *     Designed to be invoked by Claude Desktop / Cursor / Continue
+ *     as a subprocess. Reads stdin for JSON-RPC, writes stdout for
+ *     responses, stderr for log lines.
+ */
+import { mkdirSync, writeFileSync, existsSync, readFileSync, chmodSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { runMCPServer } from "../src/mcp/server.js";
+import { loadConfig, resolveMode, resolveToolGroups } from "../src/mcp/config.js";
+/** Read the real version from the installed package.json.
+ *  A hard-coded string silently goes stale and then LIES about which
+ *  build is running — exactly the thing `--version` exists to answer. */
+function packageVersion() {
+    try {
+        const here = new URL("../package.json", import.meta.url);
+        const pkg = JSON.parse(readFileSync(here, "utf-8"));
+        if (pkg.version)
+            return pkg.version;
+    }
+    catch {
+        /* fall through */
+    }
+    try {
+        const here = new URL("../../package.json", import.meta.url);
+        const pkg = JSON.parse(readFileSync(here, "utf-8"));
+        if (pkg.version)
+            return pkg.version;
+    }
+    catch {
+        /* fall through */
+    }
+    return "unknown";
+}
+async function main() {
+    const cmd = process.argv[2];
+    if (cmd === "init") {
+        await initWizard();
+        return;
+    }
+    if (cmd === "--help" || cmd === "-h" || cmd === "help") {
+        printHelp();
+        return;
+    }
+    if (cmd === "--version" || cmd === "-v") {
+        console.log(`suprafx-agent-sdk ${packageVersion()}`);
+        return;
+    }
+    const cfg = loadConfig();
+    const mode = resolveMode();
+    const groups = resolveToolGroups();
+    if (!cfg.delegatePrivKeyHex) {
+        process.stderr.write("[suprafx-mcp] no delegate key configured. Running in READ-ONLY mode.\n" +
+            "[suprafx-mcp] To enable trading tools, run: `suprafx-mcp init`\n");
+    }
+    else if (mode === "autonomous") {
+        process.stderr.write("[suprafx-mcp] AUTONOMOUS mode: money tools will NOT ask for per-call\n" +
+            "[suprafx-mcp] acknowledgement. Every write is real money.\n");
+    }
+    if (!cfg.masterAddress) {
+        process.stderr.write("[suprafx-mcp] no master address set — balance, lock and open-order reads\n" +
+            "[suprafx-mcp] need it. Set SUPRAFX_MASTER_ADDRESS or re-run `suprafx-mcp init`.\n");
+    }
+    await runMCPServer({
+        baseUrl: cfg.baseUrl,
+        delegatePrivKeyHex: cfg.delegatePrivKeyHex,
+        masterAddress: cfg.masterAddress,
+        mode,
+        groups,
+    });
+}
+function printHelp() {
+    console.log(`
+suprafx-mcp — Model Context Protocol server for SupraFX
+
+Usage:
+  suprafx-mcp            Run the MCP server over stdio (default for Claude Desktop)
+  suprafx-mcp init       Interactive setup wizard — writes ~/.suprafx/config.json
+  suprafx-mcp --help     Show this help
+  suprafx-mcp --version  Print the installed package version
+
+Flags:
+  --tools=read                Expose ONLY read tools, even with a key loaded
+                              (a keyed monitor agent that cannot trade).
+                              Also: --tools=read,cancel  (cancel-only)
+                                    --tools=read,trade   (no cancel class)
+                              Default: every class the key entitles you to.
+  --allow-dangerous           AUTONOMOUS mode: money tools stop requiring a
+                              per-call 'acknowledged:true'. Without this the
+                              server is GUARDED — every write asks once.
+
+Environment overrides:
+  SUPRAFX_DELEGATE_PRIV_HEX   Hex of delegate ed25519 private key (32 bytes)
+  SUPRAFX_MASTER_ADDRESS      Your MASTER StarKey address — balances, locks and
+                              open orders all live there, not on the delegate
+  SUPRAFX_BASE_URL            Override the dApp base URL (default https://suprafx.ai)
+  SUPRAFX_ALLOW_DANGEROUS=1   Same as --allow-dangerous
+  SUPRAFX_TOOLS=read,cancel   Same as --tools=
+
+One-line install (Claude Code):
+
+  npm install -g suprafx-agent-sdk
+  claude mcp add --scope user suprafx -- suprafx-mcp
+
+Configure Claude Desktop by adding this to your claude_desktop_config.json:
+
+{
+  "mcpServers": {
+    "suprafx": {
+      "command": "suprafx-mcp"
+    }
+  }
+}
+
+Then restart Claude Desktop. Tools will appear in the model's tool palette.
+
+Documentation: https://github.com/jtobkin/suprafx-agent-sdk
+`);
+}
+async function initWizard() {
+    console.log("\nSupraFX MCP setup wizard\n========================\n");
+    console.log("Before you start, you need a delegate keypair authorized");
+    console.log("on chain by your master StarKey wallet.");
+    console.log("");
+    console.log("If you haven't done that yet:");
+    console.log("  1. Go to https://suprafx.ai");
+    console.log("  2. Connect StarKey, open Profile → Delegates");
+    console.log("  3. Click 'Create Delegate'");
+    console.log("  4. Click 'Generate' — a JSON file downloads to your machine.");
+    console.log("     KEEP THIS FILE SAFE. The private key inside controls trading.");
+    console.log("  5. Set per-asset caps, sign the policy with StarKey.");
+    console.log("");
+    console.log("Now paste the 32-byte hex private key (or a path to the");
+    console.log("downloaded JSON file). Press enter when done.");
+    console.log("");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q) => new Promise((resolve) => rl.question(q, (a) => resolve(a.trim())));
+    const input = await ask("Delegate private key (hex or path to JSON): ");
+    let privHex;
+    if (input.startsWith("/") || input.startsWith("~") || input.startsWith("./")) {
+        const path = input.startsWith("~") ? join(homedir(), input.slice(1)) : input;
+        if (!existsSync(path)) {
+            throw new Error(`File not found: ${path}`);
+        }
+        const j = JSON.parse(readFileSync(path, "utf-8"));
+        const key = j.delegatePrivKeyHex ?? j.privateKeyHex ?? j.privateKey ?? j.priv;
+        if (!key) {
+            throw new Error(`JSON at ${path} did not contain a recognized private-key field`);
+        }
+        privHex = String(key);
+    }
+    else {
+        privHex = input;
+    }
+    privHex = privHex.replace(/^0x/i, "").toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(privHex)) {
+        throw new Error(`Expected a 32-byte hex private key (64 hex chars). Got ${privHex.length} chars.`);
+    }
+    console.log("");
+    console.log("Now your MASTER StarKey address — the wallet you connected to");
+    console.log("suprafx.ai with, that holds the funds. Your agent needs it to read");
+    console.log("balances and locks; the delegate has no balances of its own.");
+    console.log("Saving it here means the agent never has to be told it again.");
+    console.log("");
+    let masterAddress = await ask("Master StarKey address (0x…, or enter to skip): ");
+    masterAddress = masterAddress.trim().toLowerCase();
+    if (masterAddress.length > 0) {
+        const m = masterAddress.startsWith("0x") ? masterAddress.slice(2) : masterAddress;
+        if (!/^[0-9a-f]{64}$/.test(m)) {
+            rl.close();
+            throw new Error(`Expected a 32-byte hex address (64 hex chars, 0x-prefixed). Got ${m.length} chars.`);
+        }
+        masterAddress = "0x" + m;
+    }
+    const baseUrl = await ask("SupraFX base URL (press enter for https://suprafx.ai): ");
+    rl.close();
+    const cfg = { delegatePrivKeyHex: privHex };
+    if (masterAddress.length > 0)
+        cfg.masterAddress = masterAddress;
+    if (baseUrl.length > 0)
+        cfg.baseUrl = baseUrl;
+    const cfgDir = join(homedir(), ".suprafx");
+    mkdirSync(cfgDir, { recursive: true });
+    const cfgPath = join(cfgDir, "config.json");
+    // Atomic write (temp + rename): a running suprafx-mcp hot-reloads this
+    // file, so a truncate-then-write could be read mid-rotation as a partial
+    // (invalid JSON) and flip the server to read-only. Write to a temp file
+    // with 0600 first, then rename into place (atomic on the same filesystem).
+    const tmpPath = `${cfgPath}.tmp`;
+    writeFileSync(tmpPath, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+    chmodSync(tmpPath, 0o600);
+    renameSync(tmpPath, cfgPath);
+    console.log(`\n✓ Saved to ${cfgPath} (mode 600 — owner read/write only)`);
+    console.log("");
+    if (!cfg.masterAddress) {
+        console.log("⚠ No master address saved. Balance and open-order reads will need");
+        console.log("  one passed by hand every session. Re-run `suprafx-mcp init` to add it.");
+        console.log("");
+    }
+    console.log("Next — Claude Code, one line:");
+    console.log("");
+    console.log("  claude mcp add --scope user suprafx -- suprafx-mcp");
+    console.log("");
+    console.log("Or add this to your Claude Desktop config:");
+    console.log("");
+    console.log("  ~/Library/Application Support/Claude/claude_desktop_config.json");
+    console.log("");
+    console.log(`  {
+    "mcpServers": {
+      "suprafx": {
+        "command": "suprafx-mcp"
+      }
+    }
+  }`);
+    console.log("");
+    console.log("Restart / reconnect. SupraFX tools will appear in the tool palette —");
+    console.log("the key is read at STARTUP, so a running server will not see it until then.");
+    console.log("");
+    console.log("The server starts GUARDED: every money tool asks for an explicit");
+    console.log("acknowledgement per call. For an unattended loop, launch it with");
+    console.log("--allow-dangerous. For a monitor that must never trade: --tools=read.");
+    console.log("");
+}
+main().catch((e) => {
+    process.stderr.write(`[suprafx-mcp] fatal: ${e instanceof Error ? e.message : String(e)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=suprafx-mcp.js.map

package/dist/bin/suprafx-mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suprafx-mcp.js","sourceRoot":"","sources":["../../bin/suprafx-mcp.ts"],"names":[],"mappings":"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"}

package/dist/src/asset-registry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * BFT `Amount` encoding math.
+ *
+ * The council-rust protocol denominates token amounts in `Amount`
+ * (u128) using **native per-asset decimals** — an asset with `D`
+ * on-chain decimals is carried at the `10^D` scale, exactly as the
+ * token contract reports it. See the `council-amount-decimals`
+ * decision and council-rust `chain::eth::u256_to_native_amount`.
+ * Rates are scaled by `PRICE_SCALE = 10^18` (council-rust `fees.rs`).
+ *
+ * ## This module is pure math — it embeds NO asset table
+ *
+ * Every function takes explicit `decimals` values. Per-(chain, asset)
+ * decimals are the single responsibility of the `supported_assets`
+ * registry, verified against each token's on-chain `decimals()` by
+ * `scripts/verify-asset-decimals.ts`. There is deliberately no symbol
+ * table here to drift as assets land on new chains — e.g. USDT is 6
+ * decimals on Ethereum but 18 on BNB Smart Chain.
+ *
+ * Sourcing decimals:
+ *   - server: `getAssetDecimals(chain, symbol)` — `lib/council/asset-decimals.ts`
+ *   - client: `clientAssetDecimals(chain, symbol)` — `lib/council/client-asset-decimals.ts`
+ *     (both read the `supported_assets` registry; client via `GET /api/assets`)
+ */
+/**
+ * Convert a display-unit amount to a BFT `Amount` (u128) at the asset's
+ * native scale: `displayAmount × 10^decimals`.
+ *
+ * `decimals` is the asset's on-chain decimal precision on its chain
+ * (from `supported_assets`). High-decimal assets split through 10^9 to
+ * stay within IEEE-754 safe-integer range.
+ */
+export declare function toMicroUnits(amountDisplay: number, decimals: number): bigint;
+/**
+ * Convert a display exchange rate (quote per base) to the BFT-scaled
+ * `rate` (u128).
+ *
+ * Protocol definition (council-rust `fees.rs`):
+ *   `rate / PRICE_SCALE = quote-micro-units per base-micro-unit`
+ *
+ * With native per-asset decimals on both legs:
+ *   `rate_BFT = rateDisplay × 10^(18 + quoteDecimals − baseDecimals)`
+ */
+export declare function toRateBFT(rateDisplay: number, baseDecimals: number, quoteDecimals: number): bigint;
+/**
+ * Parse a `"BASE/QUOTE"` pair string into its two uppercase symbols.
+ * @throws if the format is invalid.
+ */
+export declare function parsePair(pair: string): {
+    base: string;
+    quote: string;
+};
+/**
+ * Encode `PlaceQuote` amounts: `fill_size` in base-asset native
+ * micro-units, `rate` BFT-scaled. Caller supplies the base/quote
+ * decimals (from the `supported_assets` registry).
+ */
+export declare function encodePlaceQuoteAmounts(sizeDisplay: number, rateDisplay: number, baseDecimals: number, quoteDecimals: number): {
+    fillSizeMicro: bigint;
+    rateBFT: bigint;
+};

package/dist/src/asset-registry.js

@@ -0,0 +1,118 @@
+/**
+ * BFT `Amount` encoding math.
+ *
+ * The council-rust protocol denominates token amounts in `Amount`
+ * (u128) using **native per-asset decimals** — an asset with `D`
+ * on-chain decimals is carried at the `10^D` scale, exactly as the
+ * token contract reports it. See the `council-amount-decimals`
+ * decision and council-rust `chain::eth::u256_to_native_amount`.
+ * Rates are scaled by `PRICE_SCALE = 10^18` (council-rust `fees.rs`).
+ *
+ * ## This module is pure math — it embeds NO asset table
+ *
+ * Every function takes explicit `decimals` values. Per-(chain, asset)
+ * decimals are the single responsibility of the `supported_assets`
+ * registry, verified against each token's on-chain `decimals()` by
+ * `scripts/verify-asset-decimals.ts`. There is deliberately no symbol
+ * table here to drift as assets land on new chains — e.g. USDT is 6
+ * decimals on Ethereum but 18 on BNB Smart Chain.
+ *
+ * Sourcing decimals:
+ *   - server: `getAssetDecimals(chain, symbol)` — `lib/council/asset-decimals.ts`
+ *   - client: `clientAssetDecimals(chain, symbol)` — `lib/council/client-asset-decimals.ts`
+ *     (both read the `supported_assets` registry; client via `GET /api/assets`)
+ */
+/** `rate` fixed-point exponent. council-rust `fees.rs` PRICE_SCALE = 10^18. */
+const PRICE_SCALE_EXP = 18;
+/** Upper bound on plausible token decimals — guards against bad registry data. */
+const MAX_DECIMALS = 36;
+/** bigint exponentiation (avoids `**` for older TS lib targets). */
+function bigintPow(base, exp) {
+    if (exp < 0)
+        throw new Error(`bigintPow: negative exponent ${exp}`);
+    let result = BigInt(1);
+    for (let i = 0; i < exp; i++)
+        result *= base;
+    return result;
+}
+function assertValidDecimals(decimals, label) {
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > MAX_DECIMALS) {
+        throw new Error(`${label}: invalid decimals ${decimals} (expected integer 0..${MAX_DECIMALS})`);
+    }
+}
+/**
+ * Convert a display-unit amount to a BFT `Amount` (u128) at the asset's
+ * native scale: `displayAmount × 10^decimals`.
+ *
+ * `decimals` is the asset's on-chain decimal precision on its chain
+ * (from `supported_assets`). High-decimal assets split through 10^9 to
+ * stay within IEEE-754 safe-integer range.
+ */
+export function toMicroUnits(amountDisplay, decimals) {
+    assertValidDecimals(decimals, "toMicroUnits");
+    if (!Number.isFinite(amountDisplay) || amountDisplay < 0) {
+        throw new Error(`toMicroUnits: invalid amount ${amountDisplay}`);
+    }
+    if (decimals <= 15) {
+        // 10^15 < 2^53 — exact in float.
+        return BigInt(Math.round(amountDisplay * 10 ** decimals));
+    }
+    // Split at 9 to stay within safe float range (2^53 ≈ 9×10^15).
+    const lower = BigInt(Math.round(amountDisplay * 1e9));
+    return lower * bigintPow(BigInt(10), decimals - 9);
+}
+/**
+ * Convert a display exchange rate (quote per base) to the BFT-scaled
+ * `rate` (u128).
+ *
+ * Protocol definition (council-rust `fees.rs`):
+ *   `rate / PRICE_SCALE = quote-micro-units per base-micro-unit`
+ *
+ * With native per-asset decimals on both legs:
+ *   `rate_BFT = rateDisplay × 10^(18 + quoteDecimals − baseDecimals)`
+ */
+export function toRateBFT(rateDisplay, baseDecimals, quoteDecimals) {
+    assertValidDecimals(baseDecimals, "toRateBFT base");
+    assertValidDecimals(quoteDecimals, "toRateBFT quote");
+    if (!Number.isFinite(rateDisplay) || rateDisplay < 0) {
+        throw new Error(`toRateBFT: invalid rate ${rateDisplay}`);
+    }
+    const totalExp = PRICE_SCALE_EXP + quoteDecimals - baseDecimals;
+    if (totalExp < 0) {
+        // Quote asset has far fewer decimals than base — encoding here
+        // would truncate sub-unit precision. Refuse rather than silently
+        // lose money-precision; this is unreachable for realistic pairs.
+        throw new Error(`toRateBFT: negative scale exponent ${totalExp} (baseDec ${baseDecimals}, quoteDec ${quoteDecimals})`);
+    }
+    if (totalExp >= 9) {
+        const lower = BigInt(Math.round(rateDisplay * 1e9));
+        return lower * bigintPow(BigInt(10), totalExp - 9);
+    }
+    return BigInt(Math.round(rateDisplay * 10 ** totalExp));
+}
+/**
+ * Parse a `"BASE/QUOTE"` pair string into its two uppercase symbols.
+ * @throws if the format is invalid.
+ */
+export function parsePair(pair) {
+    const parts = pair.split("/");
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+        throw new Error(`parsePair: expected "BASE/QUOTE", got "${pair}"`);
+    }
+    return {
+        base: parts[0].trim().toUpperCase(),
+        quote: parts[1].trim().toUpperCase(),
+    };
+}
+/**
+ * Encode `PlaceQuote` amounts: `fill_size` in base-asset native
+ * micro-units, `rate` BFT-scaled. Caller supplies the base/quote
+ * decimals (from the `supported_assets` registry).
+ */
+export function encodePlaceQuoteAmounts(sizeDisplay, rateDisplay, baseDecimals, quoteDecimals) {
+    return {
+        fillSizeMicro: toMicroUnits(sizeDisplay, baseDecimals),
+        rateBFT: toRateBFT(rateDisplay, baseDecimals, quoteDecimals),
+    };
+}
+//# sourceMappingURL=asset-registry.js.map

package/dist/src/asset-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-registry.js","sourceRoot":"","sources":["../../src/asset-registry.ts"],"names":[],"mappings":"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"}

package/dist/src/client.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Thin HTTP client over the SupraFX dApp's public endpoints.
+ *
+ * Wraps the read + write surfaces documented in
+ * `docs/INTEGRATING-AGENTS.md`. No auth required for reads; writes
+ * carry their own ed25519 signature inside the BCS envelope (see
+ * `./signer.ts`).
+ *
+ * Pure fetch — no global state, no caching beyond the chain-info
+ * lookup. Safe to use from the MCP server, from a cookbook script,
+ * or as a library inside a larger agent codebase.
+ */
+export interface SupraFxClientOptions {
+    /**
+     * Base URL of the SupraFX dApp. Defaults to `https://suprafx.ai`.
+     * Override for staging or for direct validator HTTP submit.
+     */
+    baseUrl?: string;
+    /** Per-request timeout in ms. Defaults to 15000. */
+    timeoutMs?: number;
+}
+export interface ChainInfo {
+    chainId: string;
+    chainIdHashHex: string;
+    threshold: number;
+    /** Live venue also returns these; optional so older deployments parse. */
+    validatorCount?: number;
+    stateMachineVersion?: number;
+}
+export interface AssetInfo {
+    chain_id: string;
+    asset_symbol: string;
+    contract_address: string | null;
+    decimals: number;
+}
+export interface PlatformBalance {
+    asset: string;
+    available: number;
+    locked_in_orders: number;
+    locked_in_rfq: number;
+    total: number;
+}
+/** One deposit claim as `GET /api/platform/deposit` summarises it. */
+export interface DepositClaimSummary {
+    claim_id: string;
+    claimer_address: string;
+    chain: string;
+    tx_hash: string;
+    asset: string;
+    /** Decimal string, never a float. */
+    amount: string;
+    /** Raw venue status, e.g. `awaiting_council`, `rejected_wrong_vault`. */
+    status: string;
+    state: "pending" | "credited" | "rejected" | "expired";
+    created_at: string;
+    credited_at: string | null;
+    credited_batch_number: number | null;
+    rejection_reason: string | null;
+    age_seconds: number;
+    /** Pending for longer than the venue's fresh-wallet threshold. NOT a failure. */
+    stale: boolean;
+    next_step: string;
+    /**
+     * True when `state` came from the venue's ledger rather than the claim
+     * record — the money provably arrived while the record still says
+     * otherwise. `status` keeps the raw record value, so the two can disagree
+     * in one response; `state` is the one to act on.
+     */
+    reconciled_from_ledger?: boolean;
+    /**
+     * What the chain actually credited, when the venue matched a ledger entry.
+     * May differ from `amount`, which is what the depositor claimed to send.
+     */
+    credited_amount?: string | null;
+}
+/** Single-claim lookup. `found:false` is a normal answer, not an error. */
+export type DepositStatusLookup = {
+    found: true;
+    claim: DepositClaimSummary;
+} | {
+    found: false;
+    chain: string;
+    tx_hash: string;
+    state: "unclaimed";
+    next_step: string;
+};
+export interface DepositClaimList {
+    address: string;
+    claims: DepositClaimSummary[];
+    counts: {
+        pending: number;
+        stale: number;
+        credited: number;
+        rejected: number;
+        expired: number;
+        /** How many of these were only known credited via the ledger. */
+        reconciled_from_ledger?: number;
+    };
+    truncated: boolean;
+}
+/** Public delegate-policy response. Additional venue fields are preserved. */
+export interface DelegatePolicy {
+    active?: boolean;
+    master?: string;
+    master_address?: string;
+    [key: string]: unknown;
+}
+export interface OrderbookRfq {
+    id: string;
+    taker_address: string;
+    pair: string;
+    size: number;
+    remaining_size: number;
+    source_chain: string;
+    dest_chain: string;
+    reference_price: number;
+    status: string;
+    settlement_mode: string;
+    allow_partial_fills: boolean;
+    min_fill_size: number;
+    expires_at: string;
+    created_at: string;
+}
+export interface SubmitResult {
+    ok: boolean;
+    batch?: number;
+    event_hash_hex?: string;
+    code?: string;
+    detail?: string;
+    per_validator?: unknown[];
+}
+/**
+ * Stable, machine-readable error categories. An agent can branch on
+ * `code` without parsing prose, and `action` names the one thing that
+ * clears it. Mirrors the envelope Kraken ships on every command.
+ */
+export type SupraFxErrorCode = "auth" | "rate_limit" | "validation" | "not_found" | "api" | "network" | "timeout" | "seq_desync" | "needs_acknowledgement" | "read_only";
+export type SupraFxErrorAction = "authenticate" | "backoff" | "fix_input" | "reconnect" | "configure_key" | "acknowledge" | "retry" | "report";
+/** An error carrying a stable category and the action that clears it. */
+export declare class SupraFxError extends Error {
+    readonly code: SupraFxErrorCode;
+    readonly action: SupraFxErrorAction;
+    readonly status?: number;
+    readonly detail?: unknown;
+    constructor(code: SupraFxErrorCode, action: SupraFxErrorAction, message: string, opts?: {
+        status?: number;
+        detail?: unknown;
+    });
+    /** The JSON body an MCP handler returns on failure. */
+    toEnvelope(): {
+        error: SupraFxErrorCode;
+        action: SupraFxErrorAction;
+        message: string;
+        status?: number;
+        detail?: unknown;
+    };
+}
+export interface OracleQuote {
+    pair: string;
+    conversionRate: number | null;
+    updatedAt: number | null;
+    /** Age of the quote in ms at read time. */
+    ageMs: number | null;
+}
+export declare class SupraFxClient {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private cachedChainInfo;
+    private cachedClockOffset;
+    constructor(opts?: SupraFxClientOptions);
+    /**
+     * Fetch the canonical chain-id hash and validator threshold.
+     * Cached for the lifetime of the client — these values are
+     * constant per chain genesis.
+     */
+    getChainInfo(): Promise<ChainInfo>;
+    /**
+     * Difference between the venue's HTTP clock and the local clock.
+     * Best-effort only: expiry calculation must remain available when the
+     * header or endpoint is unavailable.
+     */
+    getVenueClockOffsetMs(): Promise<number>;
+    /** Current committed batch height. Useful for `expires_at_batch` math. */
+    getCurrentBatch(): Promise<number>;
+    /**
+     * Next strictly-monotonic sequence number this address must use
+     * for its next signed event. `0` for a brand-new account.
+     */
+    getSequenceNumber(address: string): Promise<number>;
+    /** All supported assets with canonical chain id + decimals. */
+    listAssets(): Promise<AssetInfo[]>;
+    /**
+     * Available + locked balances for `address` (a master Supra account).
+     * Returns an empty array if the address has no balance rows.
+     */
+    getBalances(address: string): Promise<PlatformBalance[]>;
+    /**
+     * Status of one deposit claim, keyed on the chain and the L1 transaction
+     * hash. Answers "still crediting, or failed?" — see `state`, `stale` and
+     * `next_step`. An unknown transaction is `found:false`, not an error: a
+     * deposit made without recording a claim still credits through the
+     * validator bridge, it is just not visible here.
+     */
+    getDepositStatus(chain: string, txHash: string): Promise<DepositStatusLookup>;
+    /** Every deposit claim recorded by `address` (a master account), newest first. */
+    listDepositClaims(address: string, limit?: number): Promise<DepositClaimList>;
+    /** On-chain policy currently associated with a delegate address. */
+    getDelegatePolicy(address: string): Promise<DelegatePolicy | null>;
+    /**
+     * Public orderbook: open RFQs. Filters as documented in
+     * `INTEGRATING-AGENTS.md` §2.
+     */
+    getOrderbook(filters?: {
+        pair?: string;
+        status?: string;
+        limit?: number;
+    }): Promise<OrderbookRfq[]>;
+    /**
+     * Venue oracle quote for `pair` (e.g. `"ETH/USDC"`), with the quote's
+     * age computed at read time. Quote against THIS, never an external
+     * price — and never against a stale one (see `ORACLE_STALE_MS`).
+     */
+    getOracle(pair: string): Promise<OracleQuote>;
+    submitEnvelope(endpoint: "submit-rfq" | "place-quote" | "accept-quote" | "withdraw-quote" | "cancel-rfq", bodyFieldName: string, envelopeBcsHex: string): Promise<SubmitResult>;
+    private get;
+    private post;
+}