@hypermid/sdk 1.2.0

package/README.md

@@ -0,0 +1,71 @@
+# @hypermid/sdk
+
+TypeScript / JavaScript SDK for the [HyperMid](https://hypermid.io) Partner
+API — swap, bridge, and on-ramp across 90+ chains (EVM, Solana, Bitcoin,
+Sui, NEAR, Tron, TON, XRP, Doge).
+
+```bash
+npm install @hypermid/sdk
+```
+
+## Quick start
+
+No API key required. The SDK works anonymously out of the box at the
+default fee tier — pass an API key only if you're a partner with
+custom fee terms.
+
+```ts
+import { HyperMid } from "@hypermid/sdk";
+
+// Anonymous — works immediately, no signup
+const hm = new HyperMid();
+
+// Partner with custom fees / discounts
+const hm = new HyperMid({ apiKey: process.env.HYPERMID_API_KEY });
+
+// 1. Quote
+const quote = await hm.getQuote({
+  fromChain: 1,
+  toChain: 8453,
+  fromToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC on Ethereum
+  toToken:   "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
+  fromAmount: "1000000",                                   // 1 USDC (6 decimals)
+  fromAddress: "0xYourWallet",
+  toAddress:   "0xYourWallet",
+});
+
+// 2. Execute (returns the on-chain tx to sign + submit)
+const exec = await hm.execute({ quoteId: quote.id });
+
+// 3. Status
+const status = await hm.getStatus({ txHash: "0x...", chainId: 1 });
+```
+
+## Features
+
+- `getQuote` / `execute` / `getStatus` — the swap pipeline
+- `getChains` / `getTokens` — supported chains and tokens
+- `getBalances` — multi-ecosystem wallet balances + USD totals
+- `createWebhook` — register webhook endpoints for swap / on-ramp events
+- `registerInboundReceiver` — SuperSwap V2 inbound deposits
+- On-ramp helpers — `getOnrampQuote`, `getOnrampCheckout`, `getOnrampStatus`
+
+## Authentication
+
+The API is open by default — every endpoint works without
+authentication, so you can integrate, test, and ship without a signup.
+
+An **API key is only needed if you're a partner** with negotiated terms
+(custom fee splits, fee discounts, volume tiers, higher rate limits,
+webhook events scoped to your traffic). When set, the SDK sends it as
+the `X-API-Key` header.
+
+Apply for a partner account at [partner.hypermid.io](https://partner.hypermid.io).
+
+## Documentation
+
+Full reference: <https://docs.hypermid.io>
+
+## License
+
+MIT

package/dist/chain-registry.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Unified Hypermid Chain Registry
+ *
+ * Single source of truth for all chain definitions across the Hypermid platform.
+ * Maps Hypermid chain slugs to internal numeric IDs, LiFi chain IDs, and
+ * Near Intents blockchain strings.
+ *
+ * Design:
+ *   - EVM chains keep their standard numeric chain IDs (1, 42161, 8453...)
+ *   - Non-EVM chains use human-readable string slugs ("solana", "bitcoin", "near")
+ *   - Both formats are always accepted via resolveChain()
+ *   - Protocol routing (LiFi vs Near Intents) is handled internally
+ *
+ * @example
+ * ```ts
+ * import { resolveChain, ChainSlug } from "@hypermid/sdk";
+ *
+ * // Resolve by slug or numeric ID — both work
+ * const eth = resolveChain("ethereum");   // { slug: "ethereum", numericId: 1, ... }
+ * const arb = resolveChain(42161);        // { slug: "arbitrum", numericId: 42161, ... }
+ * const sol = resolveChain("solana");     // { slug: "solana", numericId: 1151111081099710, ... }
+ * ```
+ */
+export type ChainType = "evm" | "svm" | "utxo" | "near" | "ton" | "tvm" | "xrp" | "stellar" | "cardano" | "aptos" | "starknet" | "mvm" | "aleo" | "other";
+export type Provider = "lifi" | "near-intents";
+export type DepositMode = "wallet" | "manual";
+export interface ChainEntry {
+    /** Human-readable slug — the Hypermid chain identifier */
+    slug: string;
+    /** Internal numeric chain ID (EVM chain ID, LiFi ID, or NI range ID) */
+    numericId: number;
+    /** Display name */
+    name: string;
+    /** Chain type / ecosystem */
+    type: ChainType;
+    /** Which routing backends support this chain */
+    providers: Provider[];
+    /** Chain ID that LiFi expects (undefined if LiFi doesn't support this chain) */
+    lifiChainId?: number;
+    /** Near Intents blockchain string (undefined if NI doesn't support this chain) */
+    niBlockchain?: string;
+    /** Default deposit mode */
+    depositMode: DepositMode;
+    /** Native token info */
+    nativeToken: {
+        symbol: string;
+        name: string;
+        decimals: number;
+    };
+    /** Placeholder address for dry quotes (no real funds sent) */
+    dryQuotePlaceholder?: string;
+}
+export declare const CHAIN_REGISTRY: ChainEntry[];
+/**
+ * Resolve a chain by slug (string) or numeric ID (number).
+ * Returns the ChainEntry or null if not found.
+ *
+ * @example
+ * resolveChain("ethereum")     → { slug: "ethereum", numericId: 1, ... }
+ * resolveChain(42161)          → { slug: "arbitrum", numericId: 42161, ... }
+ * resolveChain("solana")       → { slug: "solana", numericId: 1151111081099710, ... }
+ * resolveChain(1151111081099710) → { slug: "solana", numericId: 1151111081099710, ... }
+ */
+export declare function resolveChain(input: string | number): ChainEntry | null;
+/**
+ * Convert any chain identifier to the LiFi chain ID.
+ * Returns undefined if LiFi doesn't support this chain.
+ */
+export declare function toLifiChainId(input: string | number): number | undefined;
+/**
+ * Convert any chain identifier to the Near Intents blockchain string.
+ * Returns undefined if Near Intents doesn't support this chain.
+ */
+export declare function toNIBlockchain(input: string | number): string | undefined;
+/**
+ * Convert any chain identifier to the internal numeric ID.
+ * This is the canonical numeric ID used internally.
+ */
+export declare function toNumericId(input: string | number): number | undefined;
+/**
+ * Check if a chain ID belongs to a Near Intents-only chain (900_000_XXX range).
+ */
+export declare function isNIOnlyChain(input: string | number): boolean;
+/**
+ * Check if a chain supports wallet-connected deposit mode.
+ */
+export declare function supportsWalletDeposit(input: string | number): boolean;
+/**
+ * Get the dry quote placeholder address for a chain.
+ */
+export declare function getDryQuotePlaceholder(input: string | number): string | undefined;
+/**
+ * Get all registered chains.
+ */
+export declare function getAllChains(): ChainEntry[];
+/**
+ * Get chains filtered by provider.
+ */
+export declare function getChainsByProvider(provider: Provider): ChainEntry[];
+/**
+ * The Near Intents chain ID base constant (900_000_000).
+ */
+export declare const NI_CHAIN_BASE = 900000000;
+//# sourceMappingURL=chain-registry.d.ts.map

package/dist/chain-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain-registry.d.ts","sourceRoot":"","sources":["../src/chain-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,MAAM,MAAM,SAAS,GACjB,KAAK,GACL,KAAK,GACL,MAAM,GACN,MAAM,GACN,KAAK,GACL,KAAK,GACL,KAAK,GACL,SAAS,GACT,SAAS,GACT,OAAO,GACP,UAAU,GACV,KAAK,GACL,MAAM,GACN,OAAO,CAAC;AAEZ,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,cAAc,CAAC;AAC/C,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9C,MAAM,WAAW,UAAU;IACzB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,gDAAgD;IAChD,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2BAA2B;IAC3B,WAAW,EAAE,WAAW,CAAC;IACzB,wBAAwB;IACxB,WAAW,EAAE;QACX,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,8DAA8D;IAC9D,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AASD,eAAO,MAAM,cAAc,EAAE,UAAU,EA+XtC,CAAC;AAkBF;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,IAAI,CActE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAExE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAEzE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAEtE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAI7D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAGrE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAEjF;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,UAAU,EAAE,CAE3C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,UAAU,EAAE,CAEpE;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,YAAU,CAAC"}