@orkid-labs/sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,542 @@
+import { WalletClient, PublicClient, Hex } from 'viem';
+import { ethers } from 'ethers';
+
+/**
+ * Core types for the Orkid Swap API.
+ *
+ * The /route and /solve endpoints share the same response envelope. A quote is
+ * returned in the `quote` field; a solved transaction is returned in the
+ * `transaction` field when applicable.
+ */
+type OrkidChain = 'base';
+/**
+ * Token data returned by /api/v1/tokens.
+ */
+interface OrkidToken {
+    address: string;
+    symbol: string;
+    decimals: number;
+    chain: string;
+}
+interface OrkidQuote {
+    /** Human-readable amount in (e.g. "25.000000") */
+    amountIn: string;
+    /** Human-readable amount out after Orkid fee */
+    amountOut: string;
+    /** Raw atomic amount out as a string */
+    amountOutRaw: string;
+    /** USD notional of the swap input */
+    volumeUsd: number;
+    /** Human-readable rate, e.g. "0.000407 WETH/USDC" */
+    rate: string;
+    /** Best routing protocol, e.g. "aerodrome_slipstreams" */
+    protocol: string;
+    /** Pool address used for the primary hop */
+    poolAddress?: string;
+    /** Estimated price impact in basis points */
+    priceImpactBps?: number;
+}
+interface OrkidSavings {
+    /** Orkid fee in basis points (competitive — contact Orkid for pricing) */
+    orkidBps: number;
+    /** Estimated MetaMask-like fee for comparison */
+    metamaskBps: number;
+    /** Savings vs MetaMask in basis points */
+    savingsBps: number;
+    /** Estimated USD savings */
+    savingsUsd: number;
+    /** USD notional of the swap */
+    volumeUsd: number;
+    /** Human-readable savings multiplier */
+    savingsMultiplier: string;
+}
+interface OrkidTransaction {
+    /** Transaction hash when the solver submitted gaslessly */
+    txHash?: string;
+    /** Contract the transaction is sent to (TVMExecutor) */
+    to: string;
+    /** Calldata for the transaction */
+    data: string;
+    /** ETH value to send (usually 0) */
+    value: string;
+    /** Chain the tx is for */
+    chain: string;
+}
+/**
+ * Success/error envelope returned by both /route and /solve.
+ */
+interface OrkidResponse {
+    ok: boolean;
+    quote?: OrkidQuote;
+    transaction?: OrkidTransaction;
+    savings?: OrkidSavings;
+    error?: string;
+    /**
+     * False when the swap is below the solver's gasless notional floor —
+     * the client should submit the returned calldata itself (user pays gas).
+     */
+    gaslessEligible?: boolean;
+    computeMs: number;
+}
+interface OrkidRouteRequest {
+    /** Token symbol or address to sell */
+    from: string;
+    /** Token symbol or address to buy */
+    to: string;
+    /** Human-readable amount to sell, e.g. "25.0" */
+    amount: string;
+    /** Chain name, e.g. "base" */
+    chain?: string;
+    /** Explicit token-in address (recommended) */
+    fromAddress?: string;
+    /** Explicit token-in decimals (required if fromAddress is provided) */
+    fromDecimals?: number;
+    /** Explicit token-out address (recommended) */
+    toAddress?: string;
+    /** Explicit token-out decimals (required if toAddress is provided) */
+    toDecimals?: number;
+}
+interface OrkidPermit {
+    permitted: {
+        /** Token address */
+        token: string;
+        /** Raw atomic amount */
+        amount: string;
+    };
+    /** Permit2 nonce as a uint256 string */
+    nonce: string;
+    /** Unix timestamp deadline */
+    deadline: string;
+}
+interface OrkidSolveRequest extends OrkidRouteRequest {
+    /** User wallet address */
+    user: string;
+    /** Permit2 permit object (without spender) */
+    permit: OrkidPermit;
+    /** 65-byte hex signature */
+    signature: string;
+    /** If true, only return calldata and do not submit */
+    dryRun?: boolean;
+    /** Slippage in basis points (e.g. 5 = 0.05%) */
+    slippageBps?: number;
+}
+/**
+ * Client options.
+ */
+interface OrkidClientOptions {
+    /** 40-character hex Orkid API key. Optional when using a partner proxy. */
+    apiKey?: string;
+    /** Base URL for the Orkid API */
+    baseUrl?: string;
+    /** Optional fetch override */
+    fetch?: typeof fetch;
+    /**
+     * Orkid operator secret — marks usage events as test traffic (excluded from
+     * rebateable volume). Server-side only; never set this in browser code.
+     */
+    operatorSecret?: string;
+}
+/**
+ * Partner account record from GET /api/v1/account.
+ */
+interface OrkidAccount {
+    id: string;
+    slug: string;
+    name: string;
+    contact_email?: string;
+    /** Rebate rate in basis points (e.g. 3 = 0.03%) */
+    rebate_bps: number;
+    rebate_active: boolean;
+    notes?: string;
+    created_at?: string;
+    updated_at?: string;
+}
+interface OrkidAccountResponse {
+    ok: boolean;
+    account?: OrkidAccount;
+    error?: string;
+}
+/**
+ * A single usage event from GET /api/v1/usage.
+ */
+interface OrkidUsageEvent {
+    id: number;
+    account_id: string;
+    api_key_id: string;
+    event_type: 'route' | 'solve' | string;
+    chain?: string;
+    token_in?: string;
+    token_out?: string;
+    amount_in_raw?: string | number | null;
+    amount_out_raw?: string | number | null;
+    volume_usd?: number | null;
+    savings_usd?: number | null;
+    fee_bps?: number | null;
+    tx_hash?: string | null;
+    request_ip?: string | null;
+    is_dry_run: boolean;
+    metadata?: Record<string, unknown>;
+    created_at: string;
+}
+interface OrkidUsageResponse {
+    ok: boolean;
+    events?: OrkidUsageEvent[];
+    total_volume_usd?: number;
+    total_savings_usd?: number;
+    error?: string;
+}
+/**
+ * A monthly rebate ledger row from GET /api/v1/rebates.
+ */
+interface OrkidRebate {
+    id: number;
+    account_id: string;
+    /** Rebate frequency, e.g. "monthly" */
+    period: string;
+    /** ISO timestamp of the period start (month) */
+    period_start: string;
+    volume_usd: number;
+    rebate_bps: number;
+    rebate_usd: number;
+    status: 'accrued' | 'paid' | 'voided' | string;
+    settled_at?: string | null;
+    settlement_tx_hash?: string | null;
+    created_at?: string;
+}
+interface OrkidRebatesResponse {
+    ok: boolean;
+    rebates?: OrkidRebate[];
+    error?: string;
+}
+
+/** Sandbox base URL — dry-run mode, real quotes but no execution. */
+declare const SANDBOX_BASE_URL = "https://sandbox.orkidlabs.com";
+/**
+ * HTTP client for the Orkid /api/v1 endpoints.
+ *
+ * Example:
+ *
+ * ```ts
+ * const orkid = new OrkidClient({ apiKey: process.env.ORKID_API_KEY })
+ * const quote = await orkid.getQuote({ from: 'USDC', to: 'WETH', amount: '25', chain: 'base' })
+ * ```
+ */
+declare class OrkidClient {
+    private apiKey;
+    private operatorSecret;
+    private baseUrl;
+    private fetch;
+    constructor(options: OrkidClientOptions);
+    private baseHeaders;
+    /**
+     * Anonymous (keyless) browser calls can hit 403 when the anti-scrape token
+     * is missing or expired. Recover by hitting /api/v1/handshake (issues a
+     * fresh bound cookie) and retrying once.
+     */
+    private fetchWithHandshake;
+    /**
+     * Get an executable quote for a swap.
+     */
+    getQuote(request: OrkidRouteRequest): Promise<OrkidResponse>;
+    /**
+     * Solve a swap gaslessly.
+     */
+    solve(request: OrkidSolveRequest): Promise<OrkidResponse>;
+    /**
+     * Convenience wrapper: get a quote then dry-run solve the same swap with a
+     * pre-signed permit. Useful for testing signatures before live execution.
+     */
+    dryRun(request: Omit<OrkidSolveRequest, 'dryRun'>): Promise<OrkidResponse>;
+    /**
+     * Fetch a list of tokens for a chain from the Orkid token search endpoint.
+     * This is a convenience; the API key is optional for this read-only endpoint.
+     */
+    listTokens(params?: {
+        chain: string;
+        search?: string;
+        limit?: number;
+    }): Promise<{
+        ok: boolean;
+        tokens?: {
+            address: string;
+            symbol: string;
+            decimals: number;
+            chain: string;
+        }[];
+        error?: string;
+    }>;
+    /**
+     * Fetch the partner account associated with this API key.
+     */
+    getAccount(): Promise<OrkidAccountResponse>;
+    /**
+     * Fetch usage events for the partner account. Optionally filter by month
+     * (`period: 'YYYY-MM'`) and event type (`'route'` | `'solve'`).
+     */
+    getUsage(params?: {
+        period?: string;
+        eventType?: 'route' | 'solve' | string;
+        limit?: number;
+    }): Promise<OrkidUsageResponse>;
+    /**
+     * Fetch the rebate ledger for the partner account. Optionally filter by
+     * month (`period: 'YYYY-MM'`).
+     */
+    getRebates(params?: {
+        period?: string;
+    }): Promise<OrkidRebatesResponse>;
+    /**
+     * Health check on the API. The API key is optional here.
+     */
+    getStatus(): Promise<{
+        ok: boolean;
+        [key: string]: unknown;
+    }>;
+    /**
+     * Confirm a user-submitted swap (user-pays-gas mode, e.g. below the gasless
+     * floor). The API verifies the tx on-chain and counts it as a real solve —
+     * this is what makes user-paid volume rebate-eligible.
+     */
+    confirmTransaction(txHash: string, chain?: string): Promise<{
+        ok: boolean;
+        confirmed?: boolean;
+        eventId?: number;
+        txHash?: string;
+        chain?: string;
+        error?: string;
+    }>;
+    private get;
+    private post;
+}
+
+/**
+ * Chain metadata for Orkid swaps.
+ *
+ * Base, Ethereum, Arbitrum, and Polygon are live with production TVMExecutor
+ * proxies at 30 bps. Each chain also has a sandbox TVMExecutor at 75 bps
+ * for the retail widget on orkidlabs.xyz.
+ */
+interface OrkidChainConfig {
+    id: number;
+    name: string;
+    shortName: string;
+    color: string;
+    permit2: string;
+    tvmExecutor: string;
+    /** Sandbox TVMExecutor at 75 bps for the retail widget (orkidlabs.xyz). */
+    sandboxTvmExecutor: string;
+    tychoRouter: string;
+    explorer: string;
+    rpcUrl: string;
+    nativeSymbol: string;
+    nativeDecimals: number;
+    minNotionalUsd: number;
+    isLive: boolean;
+}
+declare const PERMIT2: "0x000000000022D473030F116dDEE9F6B43aC78BA3";
+/** Canonical Permit2 contract address on all EVM chains. */
+declare function getPermit2Address(): string;
+/**
+ * Map chain identifiers to the solver/TVMExecutor config.
+ *
+ * The TVMExecutor is the `spender` that must appear in the signed Permit2
+ * PermitTransferFrom message.
+ *
+ * Production TVMExecutors charge 30 bps. Sandbox TVMExecutors charge 75 bps
+ * and are used by the retail widget on orkidlabs.xyz.
+ */
+declare const ORKID_CHAIN_CONFIG: Record<number, OrkidChainConfig>;
+/** Supported chain names. */
+declare const ORKID_CHAINS: readonly ["base", "ethereum", "arbitrum", "polygon"];
+declare function chainIdFromName(name: string): number;
+declare function chainNameFromId(chainId: number): string;
+declare function chainConfigFromName(name: string): OrkidChainConfig;
+declare function normalizeChainName(name: string): string;
+
+/**
+ * EIP-712 typed-data definition for Permit2 PermitTransferFrom.
+ *
+ * The `spender` field is part of the signed type string but is not included in
+ * the JSON `permit` object sent to /api/v1/solve.
+ */
+declare const PERMIT_TRANSFER_FROM_TYPES: {
+    readonly PermitTransferFrom: readonly [{
+        readonly name: "permitted";
+        readonly type: "TokenPermissions";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }];
+    readonly TokenPermissions: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+};
+interface OrkidPermitMessage {
+    permitted: {
+        token: string;
+        amount: string;
+    };
+    spender: string;
+    nonce: string;
+    deadline: string;
+}
+interface OrkidPermitDomain {
+    name: string;
+    chainId: number;
+    verifyingContract: `0x${string}`;
+}
+/**
+ * Build the EIP-712 domain for Permit2 on a given chain.
+ */
+declare function buildPermit2Domain(chainId: number): OrkidPermitDomain;
+/**
+ * Build the full PermitTransferFrom message (including the `spender`) that must
+ * be signed by the user.
+ */
+declare function buildPermitMessage(params: {
+    token: string;
+    amount: string;
+    nonce: string;
+    deadline: string;
+    spender: string;
+}): OrkidPermitMessage;
+/**
+ * Strip the `spender` from the signed permit to produce the object sent to
+ * /api/v1/solve.
+ */
+declare function toOrkidPermit(message: OrkidPermitMessage): OrkidPermit;
+/**
+ * Convert a human-readable token amount to raw atomic units based on decimals.
+ */
+declare function parseAmount(value: string, decimals: number): string;
+/**
+ * Format a raw atomic amount to a human-readable string.
+ */
+declare function formatAmount(raw: string, decimals: number): string;
+/**
+ * Build the permit for a swap using the Orkid TVMExecutor as the spender.
+ */
+declare function buildSwapPermit(chainName: string, token: string, amount: string, nonce: string, deadlineSeconds: number): {
+    message: OrkidPermitMessage;
+    permit: OrkidPermit;
+    chainConfig: OrkidChainConfig;
+};
+/**
+ * Compute a default deadline 1 hour from now.
+ */
+declare function defaultDeadline(): number;
+/**
+ * Permit2 contract nonce layout:
+ *
+ *   wordPos = uint248(nonce >> 8)
+ *   bitPos  = uint8(nonce)
+ *
+ * This helper constructs a nonce from a word position and bit position.
+ */
+declare function buildNonce(wordPos: bigint, bitPos: number): string;
+/**
+ * Random starting word position to avoid nonce collisions across users.
+ */
+declare function randomStartWord(): bigint;
+/**
+ * Minimal Permit2 nonceBitmap ABI and selectors.
+ */
+declare const PERMIT2_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "nonceBitmap";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "wordPos";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+}];
+
+/**
+ * viem-specific helpers for Orkid Permit2 signing.
+ *
+ * This file is optional — the core SDK has no viem dependency. Import this
+ * module if you already have viem in your project.
+ */
+
+interface OrkidSignSwapParams$1 {
+    /** User wallet address */
+    user: string;
+    /** Token-in address */
+    fromToken: string;
+    /** Token-in decimals */
+    fromDecimals: number;
+    /** Human-readable amount to sell */
+    amount: string;
+    /** Chain name, e.g. 'base' */
+    chain: string;
+    /** Optional explicit nonce. If omitted, one is found on-chain. */
+    nonce?: string;
+    /** Optional deadline (seconds). Defaults to now + 1 hour. */
+    deadline?: number;
+}
+/**
+ * Signer for Orkid Permit2 messages using a viem WalletClient.
+ */
+declare class OrkidViemPermitSigner {
+    private walletClient;
+    private publicClient;
+    constructor(walletClient: WalletClient, publicClient: PublicClient);
+    findUnusedNonce(owner: string, maxWords?: number): Promise<string>;
+    signSwap(params: OrkidSignSwapParams$1): Promise<{
+        permit: OrkidPermit;
+        signature: Hex;
+        chainConfig: OrkidChainConfig;
+    }>;
+    /**
+     * Read the ERC20 allowance of the user for the Permit2 contract.
+     */
+    getPermit2Allowance(token: string, owner: string): Promise<bigint>;
+}
+
+/**
+ * ethers v6-specific helpers for Orkid Permit2 signing.
+ *
+ * This file is optional — the core SDK has no ethers dependency. Import this
+ * module if you already have ethers in your project.
+ */
+
+interface OrkidSignSwapParams {
+    user: string;
+    fromToken: string;
+    fromDecimals: number;
+    amount: string;
+    chain: string;
+    nonce?: string;
+    deadline?: number;
+}
+declare class OrkidEthersPermitSigner {
+    private signer;
+    private provider;
+    constructor(signer: ethers.Signer, provider: ethers.Provider);
+    findUnusedNonce(owner: string, maxWords?: number): Promise<string>;
+    signSwap(params: OrkidSignSwapParams): Promise<{
+        permit: OrkidPermit;
+        signature: string;
+        chainConfig: OrkidChainConfig;
+    }>;
+    getPermit2Allowance(token: string, owner: string): Promise<bigint>;
+}
+
+export { ORKID_CHAINS, ORKID_CHAIN_CONFIG, type OrkidAccount, type OrkidAccountResponse, type OrkidChain, OrkidClient, type OrkidClientOptions, OrkidEthersPermitSigner, type OrkidPermit, type OrkidPermitDomain, type OrkidPermitMessage, type OrkidQuote, type OrkidRebate, type OrkidRebatesResponse, type OrkidResponse, type OrkidRouteRequest, type OrkidSavings, type OrkidSignSwapParams$1 as OrkidSignSwapParams, type OrkidSolveRequest, type OrkidToken, type OrkidTransaction, type OrkidUsageEvent, type OrkidUsageResponse, OrkidViemPermitSigner, PERMIT2, PERMIT2_ABI, PERMIT_TRANSFER_FROM_TYPES, SANDBOX_BASE_URL, buildNonce, buildPermit2Domain, buildPermitMessage, buildSwapPermit, chainConfigFromName, chainIdFromName, chainNameFromId, defaultDeadline, formatAmount, getPermit2Address, normalizeChainName, parseAmount, randomStartWord, toOrkidPermit };