@ampvaleo/x402-hyperliquid-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Valeo Protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @ampvaleo/x402-hyperliquid-core
+
+Types, Hyperliquid chain constants, canonical EIP-712 `HyperliquidTransaction:SendAsset` helpers, and Base64 JSON helpers for the `X-PAYMENT` header.
+
+```ts
+import { buildSendAssetTypedData, testnet } from "@ampvaleo/x402-hyperliquid-core";
+
+const typed = buildSendAssetTypedData({
+  chainId: testnet.chainId,
+  message: {
+    hyperliquidChain: "Testnet",
+    destination: "0x…",
+    sourceDex: "spot",
+    destinationDex: "spot",
+    token: "USDC:0x…",
+    amount: "0.01",
+    fromSubAccount: "",
+    nonce: 1_700_000_000_000n,
+  },
+});
+```
+
+See the [root README](../../README.md) for context.

package/dist/index.cjs

@@ -0,0 +1,198 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ALL_SEND_ASSET_EIP712_TYPES: () => ALL_SEND_ASSET_EIP712_TYPES,
+  DEFAULT_USDC_TOKEN: () => DEFAULT_USDC_TOKEN,
+  EIP712_DOMAIN_TYPES: () => EIP712_DOMAIN_TYPES,
+  EIP712_VERifyingContract: () => EIP712_VERifyingContract,
+  HYPERLIQUID_SENDASSET_SCHEME: () => HYPERLIQUID_SENDASSET_SCHEME,
+  SEND_ASSET_PRIMARY_TYPE: () => SEND_ASSET_PRIMARY_TYPE,
+  SEND_ASSET_TYPES: () => SEND_ASSET_TYPES,
+  SPOT_META_INFO_ENDPOINTS: () => SPOT_META_INFO_ENDPOINTS,
+  VIEM_SEND_ASSET_TYPES: () => VIEM_SEND_ASSET_TYPES,
+  buildDomain: () => buildDomain,
+  buildSendAssetTypedData: () => buildSendAssetTypedData,
+  decodePaymentHeader: () => decodePaymentHeader,
+  encodePaymentHeader: () => encodePaymentHeader,
+  getAmountDecimalsForToken: () => getAmountDecimalsForToken,
+  getChainConfig: () => getChainConfig,
+  getTokenString: () => getTokenString,
+  mainnet: () => mainnet,
+  registerToken: () => registerToken,
+  registerTokenAmountDecimals: () => registerTokenAmountDecimals,
+  resolveTokenString: () => resolveTokenString,
+  testnet: () => testnet
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/chains.ts
+var HYPERLIQUID_SENDASSET_SCHEME = "hyperliquid-sendasset-v1";
+var ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+var EIP712_VERifyingContract = ZERO_ADDRESS;
+var mainnet = {
+  key: "mainnet",
+  chainId: 999n,
+  signatureChainId: "0x3e7",
+  hyperliquidLabel: "Mainnet",
+  exchangeUrl: "https://api.hyperliquid.xyz/exchange",
+  network: "hyperliquid-mainnet"
+};
+var testnet = {
+  key: "testnet",
+  chainId: 998n,
+  signatureChainId: "0x3e6",
+  hyperliquidLabel: "Testnet",
+  exchangeUrl: "https://api.hyperliquid-testnet.xyz/exchange",
+  network: "hyperliquid-testnet"
+};
+function getChainConfig(chain) {
+  return chain === "mainnet" ? mainnet : testnet;
+}
+
+// src/tokens.ts
+var SPOT_META_INFO_ENDPOINTS = {
+  mainnet: "https://api.hyperliquid.xyz/info",
+  testnet: "https://api.hyperliquid-testnet.xyz/info"
+};
+var DEFAULT_USDC_TOKEN = {
+  mainnet: "USDC:0x6d1e7cde53ba9467b783cb7c530ce054",
+  testnet: "USDC:0xeb62eee3685fc4c43992febcd9e75443"
+};
+var amountDecimalsByFullToken = /* @__PURE__ */ new Map([
+  [DEFAULT_USDC_TOKEN.mainnet, 8],
+  [DEFAULT_USDC_TOKEN.testnet, 8]
+]);
+var custom = /* @__PURE__ */ new Map();
+function registryKey(chain, symbol) {
+  return `${chain}:${symbol.toUpperCase()}`;
+}
+function registerTokenAmountDecimals(fullTokenString, weiDecimals) {
+  amountDecimalsByFullToken.set(fullTokenString, weiDecimals);
+}
+function getAmountDecimalsForToken(fullTokenString) {
+  const d = amountDecimalsByFullToken.get(fullTokenString);
+  if (d === void 0) {
+    throw new Error(
+      `No amount decimals registered for token "${fullTokenString}". Call registerTokenAmountDecimals() (weiDecimals from spotMeta).`
+    );
+  }
+  return d;
+}
+function registerToken(chain, symbol, tokenString, amountDecimals) {
+  custom.set(registryKey(chain, symbol), tokenString);
+  if (amountDecimals !== void 0) {
+    registerTokenAmountDecimals(tokenString, amountDecimals);
+  }
+}
+function getTokenString(chain, symbol) {
+  return custom.get(registryKey(chain, symbol));
+}
+function resolveTokenString(chain, symbol) {
+  const upper = symbol.toUpperCase();
+  const customHit = getTokenString(chain, upper);
+  if (customHit) return customHit;
+  if (upper === "USDC") return DEFAULT_USDC_TOKEN[chain];
+  throw new Error(`Unknown token symbol "${symbol}" for ${chain}`);
+}
+
+// src/eip712.ts
+var SEND_ASSET_PRIMARY_TYPE = "HyperliquidTransaction:SendAsset";
+var EIP712_DOMAIN_TYPES = [
+  { name: "name", type: "string" },
+  { name: "version", type: "string" },
+  { name: "chainId", type: "uint256" },
+  { name: "verifyingContract", type: "address" }
+];
+var SEND_ASSET_TYPES = [
+  { name: "hyperliquidChain", type: "string" },
+  { name: "destination", type: "string" },
+  { name: "sourceDex", type: "string" },
+  { name: "destinationDex", type: "string" },
+  { name: "token", type: "string" },
+  { name: "amount", type: "string" },
+  { name: "fromSubAccount", type: "string" },
+  { name: "nonce", type: "uint64" }
+];
+var ALL_SEND_ASSET_EIP712_TYPES = {
+  EIP712Domain: EIP712_DOMAIN_TYPES,
+  [SEND_ASSET_PRIMARY_TYPE]: SEND_ASSET_TYPES
+};
+var VIEM_SEND_ASSET_TYPES = {
+  [SEND_ASSET_PRIMARY_TYPE]: SEND_ASSET_TYPES
+};
+function buildDomain(chainId) {
+  return {
+    name: "HyperliquidSignTransaction",
+    version: "1",
+    chainId,
+    verifyingContract: EIP712_VERifyingContract
+  };
+}
+function buildSendAssetTypedData(params) {
+  return {
+    domain: buildDomain(params.chainId),
+    types: ALL_SEND_ASSET_EIP712_TYPES,
+    primaryType: SEND_ASSET_PRIMARY_TYPE,
+    message: params.message
+  };
+}
+
+// src/encode.ts
+var import_node_buffer = require("buffer");
+function encodePaymentHeader(payload) {
+  return import_node_buffer.Buffer.from(JSON.stringify(payload), "utf8").toString("base64");
+}
+function normalizeBase64(b64) {
+  const normalized = b64.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = (4 - normalized.length % 4) % 4;
+  return normalized + "=".repeat(pad);
+}
+function decodePaymentHeader(header) {
+  const trimmed = header.trim();
+  const json = import_node_buffer.Buffer.from(normalizeBase64(trimmed), "base64").toString("utf8");
+  return JSON.parse(json);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ALL_SEND_ASSET_EIP712_TYPES,
+  DEFAULT_USDC_TOKEN,
+  EIP712_DOMAIN_TYPES,
+  EIP712_VERifyingContract,
+  HYPERLIQUID_SENDASSET_SCHEME,
+  SEND_ASSET_PRIMARY_TYPE,
+  SEND_ASSET_TYPES,
+  SPOT_META_INFO_ENDPOINTS,
+  VIEM_SEND_ASSET_TYPES,
+  buildDomain,
+  buildSendAssetTypedData,
+  decodePaymentHeader,
+  encodePaymentHeader,
+  getAmountDecimalsForToken,
+  getChainConfig,
+  getTokenString,
+  mainnet,
+  registerToken,
+  registerTokenAmountDecimals,
+  resolveTokenString,
+  testnet
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/chains.ts","../src/tokens.ts","../src/eip712.ts","../src/encode.ts"],"sourcesContent":["export {\n  EIP712_VERifyingContract,\n  HYPERLIQUID_SENDASSET_SCHEME,\n  getChainConfig,\n  mainnet,\n  testnet,\n  type HyperliquidChainConfig,\n  type HyperliquidChainName,\n} from \"./chains.js\";\nexport {\n  DEFAULT_USDC_TOKEN,\n  SPOT_META_INFO_ENDPOINTS,\n  getAmountDecimalsForToken,\n  getTokenString,\n  registerToken,\n  registerTokenAmountDecimals,\n  resolveTokenString,\n} from \"./tokens.js\";\nexport type {\n  HyperliquidPaymentExtra,\n  HyperliquidSignatureComponents,\n  PaymentPayload,\n  PaymentRequirements,\n  SendAssetEip712Message,\n  SendAssetExchangeAction,\n} from \"./types.js\";\nexport {\n  ALL_SEND_ASSET_EIP712_TYPES,\n  EIP712_DOMAIN_TYPES,\n  SEND_ASSET_PRIMARY_TYPE,\n  SEND_ASSET_TYPES,\n  VIEM_SEND_ASSET_TYPES,\n  buildDomain,\n  buildSendAssetTypedData,\n  type BuildSendAssetTypedDataParams,\n  type SendAssetTypedData,\n} from \"./eip712.js\";\nexport { decodePaymentHeader, encodePaymentHeader } from \"./encode.js\";\n","import type { Address, Hex } from \"viem\";\n\n/** x402 scheme id for HyperCore sendAsset payments */\nexport const HYPERLIQUID_SENDASSET_SCHEME = \"hyperliquid-sendasset-v1\" as const;\n\nexport type HyperliquidChainName = \"mainnet\" | \"testnet\";\n\nexport interface HyperliquidChainConfig {\n  /** HyperEVM chain id — must match wallet EIP-712 domain chainId */\n  chainId: bigint;\n  /** Hex chain id sent on the exchange action (e.g. 0x3e7) */\n  signatureChainId: Hex;\n  /** Mainnet / Testnet label used in EIP-712 message and API action */\n  hyperliquidLabel: \"Mainnet\" | \"Testnet\";\n  /** Public exchange HTTP API */\n  exchangeUrl: string;\n  /** Network string echoed in PaymentRequirements */\n  network: string;\n  key: HyperliquidChainName;\n}\n\nconst ZERO_ADDRESS =\n  \"0x0000000000000000000000000000000000000000\" as const satisfies Address;\n\nexport const EIP712_VERifyingContract: Address = ZERO_ADDRESS;\n\nexport const mainnet: HyperliquidChainConfig = {\n  key: \"mainnet\",\n  chainId: 999n,\n  signatureChainId: \"0x3e7\",\n  hyperliquidLabel: \"Mainnet\",\n  exchangeUrl: \"https://api.hyperliquid.xyz/exchange\",\n  network: \"hyperliquid-mainnet\",\n};\n\nexport const testnet: HyperliquidChainConfig = {\n  key: \"testnet\",\n  chainId: 998n,\n  signatureChainId: \"0x3e6\",\n  hyperliquidLabel: \"Testnet\",\n  exchangeUrl: \"https://api.hyperliquid-testnet.xyz/exchange\",\n  network: \"hyperliquid-testnet\",\n};\n\nexport function getChainConfig(\n  chain: HyperliquidChainName,\n): HyperliquidChainConfig {\n  return chain === \"mainnet\" ? mainnet : testnet;\n}\n","import type { HyperliquidChainName } from \"./chains.js\";\n\n/**\n * Hyperliquid publishes spot token metadata via POST `{ \"type\": \"spotMeta\" }` to `/info`:\n * - Mainnet: https://api.hyperliquid.xyz/info\n * - Testnet: https://api.hyperliquid-testnet.xyz/info\n *\n * Each token entry includes `szDecimals` (display / size precision) and `weiDecimals` (unit for\n * balances and for `amount` in EIP-712 `HyperliquidTransaction:SendAsset`). **Verification must\n * parse decimal `amount` strings using `weiDecimals`**, not assumptions from EVM USDC (6) or from\n * `szDecimals` alone.\n *\n * Last cross-check (automated): USDC on mainnet + testnet both reported `weiDecimals: 8` and\n * `szDecimals: 8`. If `spotMeta` changes, update `DEFAULT_TOKEN_AMOUNT_DECIMALS` and/or run your\n * own `spotMeta` fetch before production deploys.\n */\nexport const SPOT_META_INFO_ENDPOINTS: Record<HyperliquidChainName, string> = {\n  mainnet: \"https://api.hyperliquid.xyz/info\",\n  testnet: \"https://api.hyperliquid-testnet.xyz/info\",\n};\n\n/** Default USDC spot token ids from Hyperliquid spotMeta (`tokenId` field). */\nexport const DEFAULT_USDC_TOKEN: Record<HyperliquidChainName, string> = {\n  mainnet: \"USDC:0x6d1e7cde53ba9467b783cb7c530ce054\",\n  testnet: \"USDC:0xeb62eee3685fc4c43992febcd9e75443\",\n};\n\n/**\n * `amount` string precision for `parseUnits` / server-side comparisons, keyed by full HL token\n * string (`SYMBOL:0x…`). Values must match **`weiDecimals`** from `spotMeta` for that token.\n */\nconst amountDecimalsByFullToken = new Map<string, number>([\n  [DEFAULT_USDC_TOKEN.mainnet, 8],\n  [DEFAULT_USDC_TOKEN.testnet, 8],\n]);\n\n/** Custom HIP-1 style token strings: SYMBOL:0x... */\nconst custom = new Map<string, string>();\n\nfunction registryKey(chain: HyperliquidChainName, symbol: string): string {\n  return `${chain}:${symbol.toUpperCase()}`;\n}\n\n/**\n * Register how many fractional digits the `amount` field uses for this full token string\n * (must match `weiDecimals` from `spotMeta` for that token).\n */\nexport function registerTokenAmountDecimals(\n  fullTokenString: string,\n  weiDecimals: number,\n): void {\n  amountDecimalsByFullToken.set(fullTokenString, weiDecimals);\n}\n\n/**\n * Decimals used when interpreting `action.amount` / `maxAmountRequired` decimal strings for this\n * token (Hyperliquid `weiDecimals`).\n */\nexport function getAmountDecimalsForToken(fullTokenString: string): number {\n  const d = amountDecimalsByFullToken.get(fullTokenString);\n  if (d === undefined) {\n    throw new Error(\n      `No amount decimals registered for token \"${fullTokenString}\". Call registerTokenAmountDecimals() (weiDecimals from spotMeta).`,\n    );\n  }\n  return d;\n}\n\n/**\n * Register a custom token string for a chain (e.g. HIP-1 spot assets).\n * Symbol is matched case-insensitively.\n * Pass `amountDecimals` (weiDecimals from spotMeta) so verification can parse amounts.\n */\nexport function registerToken(\n  chain: HyperliquidChainName,\n  symbol: string,\n  tokenString: string,\n  amountDecimals?: number,\n): void {\n  custom.set(registryKey(chain, symbol), tokenString);\n  if (amountDecimals !== undefined) {\n    registerTokenAmountDecimals(tokenString, amountDecimals);\n  }\n}\n\nexport function getTokenString(\n  chain: HyperliquidChainName,\n  symbol: string,\n): string | undefined {\n  return custom.get(registryKey(chain, symbol));\n}\n\n/** Resolve USDC or a previously registered custom symbol. */\nexport function resolveTokenString(\n  chain: HyperliquidChainName,\n  symbol: string,\n): string {\n  const upper = symbol.toUpperCase();\n  const customHit = getTokenString(chain, upper);\n  if (customHit) return customHit;\n  if (upper === \"USDC\") return DEFAULT_USDC_TOKEN[chain];\n  throw new Error(`Unknown token symbol \"${symbol}\" for ${chain}`);\n}\n","import type { TypedDataDomain, TypedDataParameter } from \"viem\";\n\nimport { EIP712_VERifyingContract } from \"./chains.js\";\nimport type { SendAssetEip712Message } from \"./types.js\";\n\n/** Primary type — must match Hyperliquid's signer exactly */\nexport const SEND_ASSET_PRIMARY_TYPE = \"HyperliquidTransaction:SendAsset\" as const;\n\n/** Frozen EIP-712 types — do not modify field order or names */\nexport const EIP712_DOMAIN_TYPES: TypedDataParameter[] = [\n  { name: \"name\", type: \"string\" },\n  { name: \"version\", type: \"string\" },\n  { name: \"chainId\", type: \"uint256\" },\n  { name: \"verifyingContract\", type: \"address\" },\n];\n\nexport const SEND_ASSET_TYPES: TypedDataParameter[] = [\n  { name: \"hyperliquidChain\", type: \"string\" },\n  { name: \"destination\", type: \"string\" },\n  { name: \"sourceDex\", type: \"string\" },\n  { name: \"destinationDex\", type: \"string\" },\n  { name: \"token\", type: \"string\" },\n  { name: \"amount\", type: \"string\" },\n  { name: \"fromSubAccount\", type: \"string\" },\n  { name: \"nonce\", type: \"uint64\" },\n];\n\nexport const ALL_SEND_ASSET_EIP712_TYPES = {\n  EIP712Domain: EIP712_DOMAIN_TYPES,\n  [SEND_ASSET_PRIMARY_TYPE]: SEND_ASSET_TYPES,\n} as const;\n\n/** Use with viem/ethers signTypedData — omit EIP712Domain (domain is passed separately). */\nexport const VIEM_SEND_ASSET_TYPES = {\n  [SEND_ASSET_PRIMARY_TYPE]: SEND_ASSET_TYPES,\n} as const;\n\nexport interface BuildSendAssetTypedDataParams {\n  /** HyperEVM chain id (999 mainnet / 998 testnet) — wallet must be on this chain */\n  chainId: bigint;\n  message: SendAssetEip712Message;\n}\n\nexport interface SendAssetTypedData {\n  domain: TypedDataDomain;\n  types: typeof ALL_SEND_ASSET_EIP712_TYPES;\n  primaryType: typeof SEND_ASSET_PRIMARY_TYPE;\n  message: SendAssetEip712Message;\n}\n\nexport function buildDomain(chainId: bigint): TypedDataDomain {\n  return {\n    name: \"HyperliquidSignTransaction\",\n    version: \"1\",\n    chainId,\n    verifyingContract: EIP712_VERifyingContract,\n  };\n}\n\n/**\n * Builds EIP-712 typed data for HyperCore sendAsset — domain, types, and message\n * match Hyperliquid's signing spec exactly.\n */\nexport function buildSendAssetTypedData(\n  params: BuildSendAssetTypedDataParams,\n): SendAssetTypedData {\n  return {\n    domain: buildDomain(params.chainId),\n    types: ALL_SEND_ASSET_EIP712_TYPES,\n    primaryType: SEND_ASSET_PRIMARY_TYPE,\n    message: params.message,\n  };\n}\n","import { Buffer } from \"node:buffer\";\n\nimport type { PaymentPayload } from \"./types.js\";\n\n/**\n * Encode payment payload for the X-PAYMENT header: standard Base64 of UTF-8 JSON.\n */\nexport function encodePaymentHeader(payload: PaymentPayload): string {\n  return Buffer.from(JSON.stringify(payload), \"utf8\").toString(\"base64\");\n}\n\nfunction normalizeBase64(b64: string): string {\n  const normalized = b64.replace(/-/g, \"+\").replace(/_/g, \"/\");\n  const pad = (4 - (normalized.length % 4)) % 4;\n  return normalized + \"=\".repeat(pad);\n}\n\nexport function decodePaymentHeader(header: string): PaymentPayload {\n  const trimmed = header.trim();\n  const json = Buffer.from(normalizeBase64(trimmed), \"base64\").toString(\"utf8\");\n  return JSON.parse(json) as PaymentPayload;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,169 @@
+import { Address, Hex, TypedDataParameter, TypedDataDomain } from 'viem';
+
+/** x402 scheme id for HyperCore sendAsset payments */
+declare const HYPERLIQUID_SENDASSET_SCHEME: "hyperliquid-sendasset-v1";
+type HyperliquidChainName = "mainnet" | "testnet";
+interface HyperliquidChainConfig {
+    /** HyperEVM chain id — must match wallet EIP-712 domain chainId */
+    chainId: bigint;
+    /** Hex chain id sent on the exchange action (e.g. 0x3e7) */
+    signatureChainId: Hex;
+    /** Mainnet / Testnet label used in EIP-712 message and API action */
+    hyperliquidLabel: "Mainnet" | "Testnet";
+    /** Public exchange HTTP API */
+    exchangeUrl: string;
+    /** Network string echoed in PaymentRequirements */
+    network: string;
+    key: HyperliquidChainName;
+}
+declare const EIP712_VERifyingContract: Address;
+declare const mainnet: HyperliquidChainConfig;
+declare const testnet: HyperliquidChainConfig;
+declare function getChainConfig(chain: HyperliquidChainName): HyperliquidChainConfig;
+
+/**
+ * Hyperliquid publishes spot token metadata via POST `{ "type": "spotMeta" }` to `/info`:
+ * - Mainnet: https://api.hyperliquid.xyz/info
+ * - Testnet: https://api.hyperliquid-testnet.xyz/info
+ *
+ * Each token entry includes `szDecimals` (display / size precision) and `weiDecimals` (unit for
+ * balances and for `amount` in EIP-712 `HyperliquidTransaction:SendAsset`). **Verification must
+ * parse decimal `amount` strings using `weiDecimals`**, not assumptions from EVM USDC (6) or from
+ * `szDecimals` alone.
+ *
+ * Last cross-check (automated): USDC on mainnet + testnet both reported `weiDecimals: 8` and
+ * `szDecimals: 8`. If `spotMeta` changes, update `DEFAULT_TOKEN_AMOUNT_DECIMALS` and/or run your
+ * own `spotMeta` fetch before production deploys.
+ */
+declare const SPOT_META_INFO_ENDPOINTS: Record<HyperliquidChainName, string>;
+/** Default USDC spot token ids from Hyperliquid spotMeta (`tokenId` field). */
+declare const DEFAULT_USDC_TOKEN: Record<HyperliquidChainName, string>;
+/**
+ * Register how many fractional digits the `amount` field uses for this full token string
+ * (must match `weiDecimals` from `spotMeta` for that token).
+ */
+declare function registerTokenAmountDecimals(fullTokenString: string, weiDecimals: number): void;
+/**
+ * Decimals used when interpreting `action.amount` / `maxAmountRequired` decimal strings for this
+ * token (Hyperliquid `weiDecimals`).
+ */
+declare function getAmountDecimalsForToken(fullTokenString: string): number;
+/**
+ * Register a custom token string for a chain (e.g. HIP-1 spot assets).
+ * Symbol is matched case-insensitively.
+ * Pass `amountDecimals` (weiDecimals from spotMeta) so verification can parse amounts.
+ */
+declare function registerToken(chain: HyperliquidChainName, symbol: string, tokenString: string, amountDecimals?: number): void;
+declare function getTokenString(chain: HyperliquidChainName, symbol: string): string | undefined;
+/** Resolve USDC or a previously registered custom symbol. */
+declare function resolveTokenString(chain: HyperliquidChainName, symbol: string): string;
+
+/** Extra Hyperliquid fields carried in PaymentRequirements.extra */
+interface HyperliquidPaymentExtra {
+    chain: "mainnet" | "testnet";
+    /** Full HL token string e.g. USDC:0x... */
+    token: string;
+    /** "" = perps / default USDC DEX, "spot" = spot balance */
+    sourceDex: "spot" | "";
+    destinationDex: "spot" | "";
+}
+/**
+ * Payment requirements for a Hyperliquid sendAsset payment (x402-compatible shape).
+ */
+interface PaymentRequirements {
+    scheme: typeof HYPERLIQUID_SENDASSET_SCHEME;
+    network: string;
+    maxAmountRequired: string;
+    resource: string;
+    description?: string;
+    mimeType?: string;
+    payTo: Hex;
+    maxTimeoutSeconds: number;
+    /** Human-readable asset label (e.g. USDC) */
+    asset: string;
+    extra: HyperliquidPaymentExtra;
+}
+/** EIP-712 message body for HyperliquidTransaction:SendAsset (signed fields only). */
+interface SendAssetEip712Message {
+    hyperliquidChain: "Mainnet" | "Testnet";
+    destination: string;
+    sourceDex: string;
+    destinationDex: string;
+    token: string;
+    amount: string;
+    fromSubAccount: string;
+    nonce: bigint;
+}
+/** Full exchange action including fields not present in the EIP-712 hash. */
+interface SendAssetExchangeAction {
+    type: "sendAsset";
+    signatureChainId: Hex;
+    hyperliquidChain: "Mainnet" | "Testnet";
+    destination: string;
+    sourceDex: string;
+    destinationDex: string;
+    token: string;
+    amount: string;
+    fromSubAccount: string;
+    nonce: number;
+}
+interface HyperliquidSignatureComponents {
+    r: Hex;
+    s: Hex;
+    v: number;
+}
+/**
+ * Signed payment payload sent in the X-PAYMENT header.
+ * Servers must validate `action` against requirements — never trust `accepted`.
+ */
+interface PaymentPayload {
+    x402Version?: number;
+    scheme: typeof HYPERLIQUID_SENDASSET_SCHEME;
+    network: string;
+    action: SendAssetExchangeAction;
+    signature: HyperliquidSignatureComponents;
+    /** Timestamp ms; must match action.nonce */
+    nonce: number;
+    signatureChainId: Hex;
+    /** Echo of what the client claims it accepted — verify against `action` only */
+    accepted: PaymentRequirements;
+}
+
+/** Primary type — must match Hyperliquid's signer exactly */
+declare const SEND_ASSET_PRIMARY_TYPE: "HyperliquidTransaction:SendAsset";
+/** Frozen EIP-712 types — do not modify field order or names */
+declare const EIP712_DOMAIN_TYPES: TypedDataParameter[];
+declare const SEND_ASSET_TYPES: TypedDataParameter[];
+declare const ALL_SEND_ASSET_EIP712_TYPES: {
+    readonly EIP712Domain: TypedDataParameter[];
+    readonly "HyperliquidTransaction:SendAsset": TypedDataParameter[];
+};
+/** Use with viem/ethers signTypedData — omit EIP712Domain (domain is passed separately). */
+declare const VIEM_SEND_ASSET_TYPES: {
+    readonly "HyperliquidTransaction:SendAsset": TypedDataParameter[];
+};
+interface BuildSendAssetTypedDataParams {
+    /** HyperEVM chain id (999 mainnet / 998 testnet) — wallet must be on this chain */
+    chainId: bigint;
+    message: SendAssetEip712Message;
+}
+interface SendAssetTypedData {
+    domain: TypedDataDomain;
+    types: typeof ALL_SEND_ASSET_EIP712_TYPES;
+    primaryType: typeof SEND_ASSET_PRIMARY_TYPE;
+    message: SendAssetEip712Message;
+}
+declare function buildDomain(chainId: bigint): TypedDataDomain;
+/**
+ * Builds EIP-712 typed data for HyperCore sendAsset — domain, types, and message
+ * match Hyperliquid's signing spec exactly.
+ */
+declare function buildSendAssetTypedData(params: BuildSendAssetTypedDataParams): SendAssetTypedData;
+
+/**
+ * Encode payment payload for the X-PAYMENT header: standard Base64 of UTF-8 JSON.
+ */
+declare function encodePaymentHeader(payload: PaymentPayload): string;
+declare function decodePaymentHeader(header: string): PaymentPayload;
+
+export { ALL_SEND_ASSET_EIP712_TYPES, type BuildSendAssetTypedDataParams, DEFAULT_USDC_TOKEN, EIP712_DOMAIN_TYPES, EIP712_VERifyingContract, HYPERLIQUID_SENDASSET_SCHEME, type HyperliquidChainConfig, type HyperliquidChainName, type HyperliquidPaymentExtra, type HyperliquidSignatureComponents, type PaymentPayload, type PaymentRequirements, SEND_ASSET_PRIMARY_TYPE, SEND_ASSET_TYPES, SPOT_META_INFO_ENDPOINTS, type SendAssetEip712Message, type SendAssetExchangeAction, type SendAssetTypedData, VIEM_SEND_ASSET_TYPES, buildDomain, buildSendAssetTypedData, decodePaymentHeader, encodePaymentHeader, getAmountDecimalsForToken, getChainConfig, getTokenString, mainnet, registerToken, registerTokenAmountDecimals, resolveTokenString, testnet };

package/dist/index.d.ts

@@ -0,0 +1,169 @@
+import { Address, Hex, TypedDataParameter, TypedDataDomain } from 'viem';
+
+/** x402 scheme id for HyperCore sendAsset payments */
+declare const HYPERLIQUID_SENDASSET_SCHEME: "hyperliquid-sendasset-v1";
+type HyperliquidChainName = "mainnet" | "testnet";
+interface HyperliquidChainConfig {
+    /** HyperEVM chain id — must match wallet EIP-712 domain chainId */
+    chainId: bigint;
+    /** Hex chain id sent on the exchange action (e.g. 0x3e7) */
+    signatureChainId: Hex;
+    /** Mainnet / Testnet label used in EIP-712 message and API action */
+    hyperliquidLabel: "Mainnet" | "Testnet";
+    /** Public exchange HTTP API */
+    exchangeUrl: string;
+    /** Network string echoed in PaymentRequirements */
+    network: string;
+    key: HyperliquidChainName;
+}
+declare const EIP712_VERifyingContract: Address;
+declare const mainnet: HyperliquidChainConfig;
+declare const testnet: HyperliquidChainConfig;
+declare function getChainConfig(chain: HyperliquidChainName): HyperliquidChainConfig;
+
+/**
+ * Hyperliquid publishes spot token metadata via POST `{ "type": "spotMeta" }` to `/info`:
+ * - Mainnet: https://api.hyperliquid.xyz/info
+ * - Testnet: https://api.hyperliquid-testnet.xyz/info
+ *
+ * Each token entry includes `szDecimals` (display / size precision) and `weiDecimals` (unit for
+ * balances and for `amount` in EIP-712 `HyperliquidTransaction:SendAsset`). **Verification must
+ * parse decimal `amount` strings using `weiDecimals`**, not assumptions from EVM USDC (6) or from
+ * `szDecimals` alone.
+ *
+ * Last cross-check (automated): USDC on mainnet + testnet both reported `weiDecimals: 8` and
+ * `szDecimals: 8`. If `spotMeta` changes, update `DEFAULT_TOKEN_AMOUNT_DECIMALS` and/or run your
+ * own `spotMeta` fetch before production deploys.
+ */
+declare const SPOT_META_INFO_ENDPOINTS: Record<HyperliquidChainName, string>;
+/** Default USDC spot token ids from Hyperliquid spotMeta (`tokenId` field). */
+declare const DEFAULT_USDC_TOKEN: Record<HyperliquidChainName, string>;
+/**
+ * Register how many fractional digits the `amount` field uses for this full token string
+ * (must match `weiDecimals` from `spotMeta` for that token).
+ */
+declare function registerTokenAmountDecimals(fullTokenString: string, weiDecimals: number): void;
+/**
+ * Decimals used when interpreting `action.amount` / `maxAmountRequired` decimal strings for this
+ * token (Hyperliquid `weiDecimals`).
+ */
+declare function getAmountDecimalsForToken(fullTokenString: string): number;
+/**
+ * Register a custom token string for a chain (e.g. HIP-1 spot assets).
+ * Symbol is matched case-insensitively.
+ * Pass `amountDecimals` (weiDecimals from spotMeta) so verification can parse amounts.
+ */
+declare function registerToken(chain: HyperliquidChainName, symbol: string, tokenString: string, amountDecimals?: number): void;
+declare function getTokenString(chain: HyperliquidChainName, symbol: string): string | undefined;
+/** Resolve USDC or a previously registered custom symbol. */
+declare function resolveTokenString(chain: HyperliquidChainName, symbol: string): string;
+
+/** Extra Hyperliquid fields carried in PaymentRequirements.extra */
+interface HyperliquidPaymentExtra {
+    chain: "mainnet" | "testnet";
+    /** Full HL token string e.g. USDC:0x... */
+    token: string;
+    /** "" = perps / default USDC DEX, "spot" = spot balance */
+    sourceDex: "spot" | "";
+    destinationDex: "spot" | "";
+}
+/**
+ * Payment requirements for a Hyperliquid sendAsset payment (x402-compatible shape).
+ */
+interface PaymentRequirements {
+    scheme: typeof HYPERLIQUID_SENDASSET_SCHEME;
+    network: string;
+    maxAmountRequired: string;
+    resource: string;
+    description?: string;
+    mimeType?: string;
+    payTo: Hex;
+    maxTimeoutSeconds: number;
+    /** Human-readable asset label (e.g. USDC) */
+    asset: string;
+    extra: HyperliquidPaymentExtra;
+}
+/** EIP-712 message body for HyperliquidTransaction:SendAsset (signed fields only). */
+interface SendAssetEip712Message {
+    hyperliquidChain: "Mainnet" | "Testnet";
+    destination: string;
+    sourceDex: string;
+    destinationDex: string;
+    token: string;
+    amount: string;
+    fromSubAccount: string;
+    nonce: bigint;
+}
+/** Full exchange action including fields not present in the EIP-712 hash. */
+interface SendAssetExchangeAction {
+    type: "sendAsset";
+    signatureChainId: Hex;
+    hyperliquidChain: "Mainnet" | "Testnet";
+    destination: string;
+    sourceDex: string;
+    destinationDex: string;
+    token: string;
+    amount: string;
+    fromSubAccount: string;
+    nonce: number;
+}
+interface HyperliquidSignatureComponents {
+    r: Hex;
+    s: Hex;
+    v: number;
+}
+/**
+ * Signed payment payload sent in the X-PAYMENT header.
+ * Servers must validate `action` against requirements — never trust `accepted`.
+ */
+interface PaymentPayload {
+    x402Version?: number;
+    scheme: typeof HYPERLIQUID_SENDASSET_SCHEME;
+    network: string;
+    action: SendAssetExchangeAction;
+    signature: HyperliquidSignatureComponents;
+    /** Timestamp ms; must match action.nonce */
+    nonce: number;
+    signatureChainId: Hex;
+    /** Echo of what the client claims it accepted — verify against `action` only */
+    accepted: PaymentRequirements;
+}
+
+/** Primary type — must match Hyperliquid's signer exactly */
+declare const SEND_ASSET_PRIMARY_TYPE: "HyperliquidTransaction:SendAsset";
+/** Frozen EIP-712 types — do not modify field order or names */
+declare const EIP712_DOMAIN_TYPES: TypedDataParameter[];
+declare const SEND_ASSET_TYPES: TypedDataParameter[];
+declare const ALL_SEND_ASSET_EIP712_TYPES: {
+    readonly EIP712Domain: TypedDataParameter[];
+    readonly "HyperliquidTransaction:SendAsset": TypedDataParameter[];
+};
+/** Use with viem/ethers signTypedData — omit EIP712Domain (domain is passed separately). */
+declare const VIEM_SEND_ASSET_TYPES: {
+    readonly "HyperliquidTransaction:SendAsset": TypedDataParameter[];
+};
+interface BuildSendAssetTypedDataParams {
+    /** HyperEVM chain id (999 mainnet / 998 testnet) — wallet must be on this chain */
+    chainId: bigint;
+    message: SendAssetEip712Message;
+}
+interface SendAssetTypedData {
+    domain: TypedDataDomain;
+    types: typeof ALL_SEND_ASSET_EIP712_TYPES;
+    primaryType: typeof SEND_ASSET_PRIMARY_TYPE;
+    message: SendAssetEip712Message;
+}
+declare function buildDomain(chainId: bigint): TypedDataDomain;
+/**
+ * Builds EIP-712 typed data for HyperCore sendAsset — domain, types, and message
+ * match Hyperliquid's signing spec exactly.
+ */
+declare function buildSendAssetTypedData(params: BuildSendAssetTypedDataParams): SendAssetTypedData;
+
+/**
+ * Encode payment payload for the X-PAYMENT header: standard Base64 of UTF-8 JSON.
+ */
+declare function encodePaymentHeader(payload: PaymentPayload): string;
+declare function decodePaymentHeader(header: string): PaymentPayload;
+
+export { ALL_SEND_ASSET_EIP712_TYPES, type BuildSendAssetTypedDataParams, DEFAULT_USDC_TOKEN, EIP712_DOMAIN_TYPES, EIP712_VERifyingContract, HYPERLIQUID_SENDASSET_SCHEME, type HyperliquidChainConfig, type HyperliquidChainName, type HyperliquidPaymentExtra, type HyperliquidSignatureComponents, type PaymentPayload, type PaymentRequirements, SEND_ASSET_PRIMARY_TYPE, SEND_ASSET_TYPES, SPOT_META_INFO_ENDPOINTS, type SendAssetEip712Message, type SendAssetExchangeAction, type SendAssetTypedData, VIEM_SEND_ASSET_TYPES, buildDomain, buildSendAssetTypedData, decodePaymentHeader, encodePaymentHeader, getAmountDecimalsForToken, getChainConfig, getTokenString, mainnet, registerToken, registerTokenAmountDecimals, resolveTokenString, testnet };

package/dist/index.js

@@ -0,0 +1,151 @@
+// src/chains.ts
+var HYPERLIQUID_SENDASSET_SCHEME = "hyperliquid-sendasset-v1";
+var ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+var EIP712_VERifyingContract = ZERO_ADDRESS;
+var mainnet = {
+  key: "mainnet",
+  chainId: 999n,
+  signatureChainId: "0x3e7",
+  hyperliquidLabel: "Mainnet",
+  exchangeUrl: "https://api.hyperliquid.xyz/exchange",
+  network: "hyperliquid-mainnet"
+};
+var testnet = {
+  key: "testnet",
+  chainId: 998n,
+  signatureChainId: "0x3e6",
+  hyperliquidLabel: "Testnet",
+  exchangeUrl: "https://api.hyperliquid-testnet.xyz/exchange",
+  network: "hyperliquid-testnet"
+};
+function getChainConfig(chain) {
+  return chain === "mainnet" ? mainnet : testnet;
+}
+
+// src/tokens.ts
+var SPOT_META_INFO_ENDPOINTS = {
+  mainnet: "https://api.hyperliquid.xyz/info",
+  testnet: "https://api.hyperliquid-testnet.xyz/info"
+};
+var DEFAULT_USDC_TOKEN = {
+  mainnet: "USDC:0x6d1e7cde53ba9467b783cb7c530ce054",
+  testnet: "USDC:0xeb62eee3685fc4c43992febcd9e75443"
+};
+var amountDecimalsByFullToken = /* @__PURE__ */ new Map([
+  [DEFAULT_USDC_TOKEN.mainnet, 8],
+  [DEFAULT_USDC_TOKEN.testnet, 8]
+]);
+var custom = /* @__PURE__ */ new Map();
+function registryKey(chain, symbol) {
+  return `${chain}:${symbol.toUpperCase()}`;
+}
+function registerTokenAmountDecimals(fullTokenString, weiDecimals) {
+  amountDecimalsByFullToken.set(fullTokenString, weiDecimals);
+}
+function getAmountDecimalsForToken(fullTokenString) {
+  const d = amountDecimalsByFullToken.get(fullTokenString);
+  if (d === void 0) {
+    throw new Error(
+      `No amount decimals registered for token "${fullTokenString}". Call registerTokenAmountDecimals() (weiDecimals from spotMeta).`
+    );
+  }
+  return d;
+}
+function registerToken(chain, symbol, tokenString, amountDecimals) {
+  custom.set(registryKey(chain, symbol), tokenString);
+  if (amountDecimals !== void 0) {
+    registerTokenAmountDecimals(tokenString, amountDecimals);
+  }
+}
+function getTokenString(chain, symbol) {
+  return custom.get(registryKey(chain, symbol));
+}
+function resolveTokenString(chain, symbol) {
+  const upper = symbol.toUpperCase();
+  const customHit = getTokenString(chain, upper);
+  if (customHit) return customHit;
+  if (upper === "USDC") return DEFAULT_USDC_TOKEN[chain];
+  throw new Error(`Unknown token symbol "${symbol}" for ${chain}`);
+}
+
+// src/eip712.ts
+var SEND_ASSET_PRIMARY_TYPE = "HyperliquidTransaction:SendAsset";
+var EIP712_DOMAIN_TYPES = [
+  { name: "name", type: "string" },
+  { name: "version", type: "string" },
+  { name: "chainId", type: "uint256" },
+  { name: "verifyingContract", type: "address" }
+];
+var SEND_ASSET_TYPES = [
+  { name: "hyperliquidChain", type: "string" },
+  { name: "destination", type: "string" },
+  { name: "sourceDex", type: "string" },
+  { name: "destinationDex", type: "string" },
+  { name: "token", type: "string" },
+  { name: "amount", type: "string" },
+  { name: "fromSubAccount", type: "string" },
+  { name: "nonce", type: "uint64" }
+];
+var ALL_SEND_ASSET_EIP712_TYPES = {
+  EIP712Domain: EIP712_DOMAIN_TYPES,
+  [SEND_ASSET_PRIMARY_TYPE]: SEND_ASSET_TYPES
+};
+var VIEM_SEND_ASSET_TYPES = {
+  [SEND_ASSET_PRIMARY_TYPE]: SEND_ASSET_TYPES
+};
+function buildDomain(chainId) {
+  return {
+    name: "HyperliquidSignTransaction",
+    version: "1",
+    chainId,
+    verifyingContract: EIP712_VERifyingContract
+  };
+}
+function buildSendAssetTypedData(params) {
+  return {
+    domain: buildDomain(params.chainId),
+    types: ALL_SEND_ASSET_EIP712_TYPES,
+    primaryType: SEND_ASSET_PRIMARY_TYPE,
+    message: params.message
+  };
+}
+
+// src/encode.ts
+import { Buffer } from "buffer";
+function encodePaymentHeader(payload) {
+  return Buffer.from(JSON.stringify(payload), "utf8").toString("base64");
+}
+function normalizeBase64(b64) {
+  const normalized = b64.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = (4 - normalized.length % 4) % 4;
+  return normalized + "=".repeat(pad);
+}
+function decodePaymentHeader(header) {
+  const trimmed = header.trim();
+  const json = Buffer.from(normalizeBase64(trimmed), "base64").toString("utf8");
+  return JSON.parse(json);
+}
+export {
+  ALL_SEND_ASSET_EIP712_TYPES,
+  DEFAULT_USDC_TOKEN,
+  EIP712_DOMAIN_TYPES,
+  EIP712_VERifyingContract,
+  HYPERLIQUID_SENDASSET_SCHEME,
+  SEND_ASSET_PRIMARY_TYPE,
+  SEND_ASSET_TYPES,
+  SPOT_META_INFO_ENDPOINTS,
+  VIEM_SEND_ASSET_TYPES,
+  buildDomain,
+  buildSendAssetTypedData,
+  decodePaymentHeader,
+  encodePaymentHeader,
+  getAmountDecimalsForToken,
+  getChainConfig,
+  getTokenString,
+  mainnet,
+  registerToken,
+  registerTokenAmountDecimals,
+  resolveTokenString,
+  testnet
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/chains.ts","../src/tokens.ts","../src/eip712.ts","../src/encode.ts"],"sourcesContent":["import type { Address, Hex } from \"viem\";\n\n/** x402 scheme id for HyperCore sendAsset payments */\nexport const HYPERLIQUID_SENDASSET_SCHEME = \"hyperliquid-sendasset-v1\" as const;\n\nexport type HyperliquidChainName = \"mainnet\" | \"testnet\";\n\nexport interface HyperliquidChainConfig {\n  /** HyperEVM chain id — must match wallet EIP-712 domain chainId */\n  chainId: bigint;\n  /** Hex chain id sent on the exchange action (e.g. 0x3e7) */\n  signatureChainId: Hex;\n  /** Mainnet / Testnet label used in EIP-712 message and API action */\n  hyperliquidLabel: \"Mainnet\" | \"Testnet\";\n  /** Public exchange HTTP API */\n  exchangeUrl: string;\n  /** Network string echoed in PaymentRequirements */\n  network: string;\n  key: HyperliquidChainName;\n}\n\nconst ZERO_ADDRESS =\n  \"0x0000000000000000000000000000000000000000\" as const satisfies Address;\n\nexport const EIP712_VERifyingContract: Address = ZERO_ADDRESS;\n\nexport const mainnet: HyperliquidChainConfig = {\n  key: \"mainnet\",\n  chainId: 999n,\n  signatureChainId: \"0x3e7\",\n  hyperliquidLabel: \"Mainnet\",\n  exchangeUrl: \"https://api.hyperliquid.xyz/exchange\",\n  network: \"hyperliquid-mainnet\",\n};\n\nexport const testnet: HyperliquidChainConfig = {\n  key: \"testnet\",\n  chainId: 998n,\n  signatureChainId: \"0x3e6\",\n  hyperliquidLabel: \"Testnet\",\n  exchangeUrl: \"https://api.hyperliquid-testnet.xyz/exchange\",\n  network: \"hyperliquid-testnet\",\n};\n\nexport function getChainConfig(\n  chain: HyperliquidChainName,\n): HyperliquidChainConfig {\n  return chain === \"mainnet\" ? mainnet : testnet;\n}\n","import type { HyperliquidChainName } from \"./chains.js\";\n\n/**\n * Hyperliquid publishes spot token metadata via POST `{ \"type\": \"spotMeta\" }` to `/info`:\n * - Mainnet: https://api.hyperliquid.xyz/info\n * - Testnet: https://api.hyperliquid-testnet.xyz/info\n *\n * Each token entry includes `szDecimals` (display / size precision) and `weiDecimals` (unit for\n * balances and for `amount` in EIP-712 `HyperliquidTransaction:SendAsset`). **Verification must\n * parse decimal `amount` strings using `weiDecimals`**, not assumptions from EVM USDC (6) or from\n * `szDecimals` alone.\n *\n * Last cross-check (automated): USDC on mainnet + testnet both reported `weiDecimals: 8` and\n * `szDecimals: 8`. If `spotMeta` changes, update `DEFAULT_TOKEN_AMOUNT_DECIMALS` and/or run your\n * own `spotMeta` fetch before production deploys.\n */\nexport const SPOT_META_INFO_ENDPOINTS: Record<HyperliquidChainName, string> = {\n  mainnet: \"https://api.hyperliquid.xyz/info\",\n  testnet: \"https://api.hyperliquid-testnet.xyz/info\",\n};\n\n/** Default USDC spot token ids from Hyperliquid spotMeta (`tokenId` field). */\nexport const DEFAULT_USDC_TOKEN: Record<HyperliquidChainName, string> = {\n  mainnet: \"USDC:0x6d1e7cde53ba9467b783cb7c530ce054\",\n  testnet: \"USDC:0xeb62eee3685fc4c43992febcd9e75443\",\n};\n\n/**\n * `amount` string precision for `parseUnits` / server-side comparisons, keyed by full HL token\n * string (`SYMBOL:0x…`). Values must match **`weiDecimals`** from `spotMeta` for that token.\n */\nconst amountDecimalsByFullToken = new Map<string, number>([\n  [DEFAULT_USDC_TOKEN.mainnet, 8],\n  [DEFAULT_USDC_TOKEN.testnet, 8],\n]);\n\n/** Custom HIP-1 style token strings: SYMBOL:0x... */\nconst custom = new Map<string, string>();\n\nfunction registryKey(chain: HyperliquidChainName, symbol: string): string {\n  return `${chain}:${symbol.toUpperCase()}`;\n}\n\n/**\n * Register how many fractional digits the `amount` field uses for this full token string\n * (must match `weiDecimals` from `spotMeta` for that token).\n */\nexport function registerTokenAmountDecimals(\n  fullTokenString: string,\n  weiDecimals: number,\n): void {\n  amountDecimalsByFullToken.set(fullTokenString, weiDecimals);\n}\n\n/**\n * Decimals used when interpreting `action.amount` / `maxAmountRequired` decimal strings for this\n * token (Hyperliquid `weiDecimals`).\n */\nexport function getAmountDecimalsForToken(fullTokenString: string): number {\n  const d = amountDecimalsByFullToken.get(fullTokenString);\n  if (d === undefined) {\n    throw new Error(\n      `No amount decimals registered for token \"${fullTokenString}\". Call registerTokenAmountDecimals() (weiDecimals from spotMeta).`,\n    );\n  }\n  return d;\n}\n\n/**\n * Register a custom token string for a chain (e.g. HIP-1 spot assets).\n * Symbol is matched case-insensitively.\n * Pass `amountDecimals` (weiDecimals from spotMeta) so verification can parse amounts.\n */\nexport function registerToken(\n  chain: HyperliquidChainName,\n  symbol: string,\n  tokenString: string,\n  amountDecimals?: number,\n): void {\n  custom.set(registryKey(chain, symbol), tokenString);\n  if (amountDecimals !== undefined) {\n    registerTokenAmountDecimals(tokenString, amountDecimals);\n  }\n}\n\nexport function getTokenString(\n  chain: HyperliquidChainName,\n  symbol: string,\n): string | undefined {\n  return custom.get(registryKey(chain, symbol));\n}\n\n/** Resolve USDC or a previously registered custom symbol. */\nexport function resolveTokenString(\n  chain: HyperliquidChainName,\n  symbol: string,\n): string {\n  const upper = symbol.toUpperCase();\n  const customHit = getTokenString(chain, upper);\n  if (customHit) return customHit;\n  if (upper === \"USDC\") return DEFAULT_USDC_TOKEN[chain];\n  throw new Error(`Unknown token symbol \"${symbol}\" for ${chain}`);\n}\n","import type { TypedDataDomain, TypedDataParameter } from \"viem\";\n\nimport { EIP712_VERifyingContract } from \"./chains.js\";\nimport type { SendAssetEip712Message } from \"./types.js\";\n\n/** Primary type — must match Hyperliquid's signer exactly */\nexport const SEND_ASSET_PRIMARY_TYPE = \"HyperliquidTransaction:SendAsset\" as const;\n\n/** Frozen EIP-712 types — do not modify field order or names */\nexport const EIP712_DOMAIN_TYPES: TypedDataParameter[] = [\n  { name: \"name\", type: \"string\" },\n  { name: \"version\", type: \"string\" },\n  { name: \"chainId\", type: \"uint256\" },\n  { name: \"verifyingContract\", type: \"address\" },\n];\n\nexport const SEND_ASSET_TYPES: TypedDataParameter[] = [\n  { name: \"hyperliquidChain\", type: \"string\" },\n  { name: \"destination\", type: \"string\" },\n  { name: \"sourceDex\", type: \"string\" },\n  { name: \"destinationDex\", type: \"string\" },\n  { name: \"token\", type: \"string\" },\n  { name: \"amount\", type: \"string\" },\n  { name: \"fromSubAccount\", type: \"string\" },\n  { name: \"nonce\", type: \"uint64\" },\n];\n\nexport const ALL_SEND_ASSET_EIP712_TYPES = {\n  EIP712Domain: EIP712_DOMAIN_TYPES,\n  [SEND_ASSET_PRIMARY_TYPE]: SEND_ASSET_TYPES,\n} as const;\n\n/** Use with viem/ethers signTypedData — omit EIP712Domain (domain is passed separately). */\nexport const VIEM_SEND_ASSET_TYPES = {\n  [SEND_ASSET_PRIMARY_TYPE]: SEND_ASSET_TYPES,\n} as const;\n\nexport interface BuildSendAssetTypedDataParams {\n  /** HyperEVM chain id (999 mainnet / 998 testnet) — wallet must be on this chain */\n  chainId: bigint;\n  message: SendAssetEip712Message;\n}\n\nexport interface SendAssetTypedData {\n  domain: TypedDataDomain;\n  types: typeof ALL_SEND_ASSET_EIP712_TYPES;\n  primaryType: typeof SEND_ASSET_PRIMARY_TYPE;\n  message: SendAssetEip712Message;\n}\n\nexport function buildDomain(chainId: bigint): TypedDataDomain {\n  return {\n    name: \"HyperliquidSignTransaction\",\n    version: \"1\",\n    chainId,\n    verifyingContract: EIP712_VERifyingContract,\n  };\n}\n\n/**\n * Builds EIP-712 typed data for HyperCore sendAsset — domain, types, and message\n * match Hyperliquid's signing spec exactly.\n */\nexport function buildSendAssetTypedData(\n  params: BuildSendAssetTypedDataParams,\n): SendAssetTypedData {\n  return {\n    domain: buildDomain(params.chainId),\n    types: ALL_SEND_ASSET_EIP712_TYPES,\n    primaryType: SEND_ASSET_PRIMARY_TYPE,\n    message: params.message,\n  };\n}\n","import { Buffer } from \"node:buffer\";\n\nimport type { PaymentPayload } from \"./types.js\";\n\n/**\n * Encode payment payload for the X-PAYMENT header: standard Base64 of UTF-8 JSON.\n */\nexport function encodePaymentHeader(payload: PaymentPayload): string {\n  return Buffer.from(JSON.stringify(payload), \"utf8\").toString(\"base64\");\n}\n\nfunction normalizeBase64(b64: string): string {\n  const normalized = b64.replace(/-/g, \"+\").replace(/_/g, \"/\");\n  const pad = (4 - (normalized.length % 4)) % 4;\n  return normalized + \"=\".repeat(pad);\n}\n\nexport function decodePaymentHeader(header: string): PaymentPayload {\n  const trimmed = header.trim();\n  const json = Buffer.from(normalizeBase64(trimmed), \"base64\").toString(\"utf8\");\n  return JSON.parse(json) as PaymentPayload;\n}\n"],"mappings":";AAGO,IAAM,+BAA+B;AAkB5C,IAAM,eACJ;AAEK,IAAM,2BAAoC;AAE1C,IAAM,UAAkC;AAAA,EAC7C,KAAK;AAAA,EACL,SAAS;AAAA,EACT,kBAAkB;AAAA,EAClB,kBAAkB;AAAA,EAClB,aAAa;AAAA,EACb,SAAS;AACX;AAEO,IAAM,UAAkC;AAAA,EAC7C,KAAK;AAAA,EACL,SAAS;AAAA,EACT,kBAAkB;AAAA,EAClB,kBAAkB;AAAA,EAClB,aAAa;AAAA,EACb,SAAS;AACX;AAEO,SAAS,eACd,OACwB;AACxB,SAAO,UAAU,YAAY,UAAU;AACzC;;;AChCO,IAAM,2BAAiE;AAAA,EAC5E,SAAS;AAAA,EACT,SAAS;AACX;AAGO,IAAM,qBAA2D;AAAA,EACtE,SAAS;AAAA,EACT,SAAS;AACX;AAMA,IAAM,4BAA4B,oBAAI,IAAoB;AAAA,EACxD,CAAC,mBAAmB,SAAS,CAAC;AAAA,EAC9B,CAAC,mBAAmB,SAAS,CAAC;AAChC,CAAC;AAGD,IAAM,SAAS,oBAAI,IAAoB;AAEvC,SAAS,YAAY,OAA6B,QAAwB;AACxE,SAAO,GAAG,KAAK,IAAI,OAAO,YAAY,CAAC;AACzC;AAMO,SAAS,4BACd,iBACA,aACM;AACN,4BAA0B,IAAI,iBAAiB,WAAW;AAC5D;AAMO,SAAS,0BAA0B,iBAAiC;AACzE,QAAM,IAAI,0BAA0B,IAAI,eAAe;AACvD,MAAI,MAAM,QAAW;AACnB,UAAM,IAAI;AAAA,MACR,4CAA4C,eAAe;AAAA,IAC7D;AAAA,EACF;AACA,SAAO;AACT;AAOO,SAAS,cACd,OACA,QACA,aACA,gBACM;AACN,SAAO,IAAI,YAAY,OAAO,MAAM,GAAG,WAAW;AAClD,MAAI,mBAAmB,QAAW;AAChC,gCAA4B,aAAa,cAAc;AAAA,EACzD;AACF;AAEO,SAAS,eACd,OACA,QACoB;AACpB,SAAO,OAAO,IAAI,YAAY,OAAO,MAAM,CAAC;AAC9C;AAGO,SAAS,mBACd,OACA,QACQ;AACR,QAAM,QAAQ,OAAO,YAAY;AACjC,QAAM,YAAY,eAAe,OAAO,KAAK;AAC7C,MAAI,UAAW,QAAO;AACtB,MAAI,UAAU,OAAQ,QAAO,mBAAmB,KAAK;AACrD,QAAM,IAAI,MAAM,yBAAyB,MAAM,SAAS,KAAK,EAAE;AACjE;;;AChGO,IAAM,0BAA0B;AAGhC,IAAM,sBAA4C;AAAA,EACvD,EAAE,MAAM,QAAQ,MAAM,SAAS;AAAA,EAC/B,EAAE,MAAM,WAAW,MAAM,SAAS;AAAA,EAClC,EAAE,MAAM,WAAW,MAAM,UAAU;AAAA,EACnC,EAAE,MAAM,qBAAqB,MAAM,UAAU;AAC/C;AAEO,IAAM,mBAAyC;AAAA,EACpD,EAAE,MAAM,oBAAoB,MAAM,SAAS;AAAA,EAC3C,EAAE,MAAM,eAAe,MAAM,SAAS;AAAA,EACtC,EAAE,MAAM,aAAa,MAAM,SAAS;AAAA,EACpC,EAAE,MAAM,kBAAkB,MAAM,SAAS;AAAA,EACzC,EAAE,MAAM,SAAS,MAAM,SAAS;AAAA,EAChC,EAAE,MAAM,UAAU,MAAM,SAAS;AAAA,EACjC,EAAE,MAAM,kBAAkB,MAAM,SAAS;AAAA,EACzC,EAAE,MAAM,SAAS,MAAM,SAAS;AAClC;AAEO,IAAM,8BAA8B;AAAA,EACzC,cAAc;AAAA,EACd,CAAC,uBAAuB,GAAG;AAC7B;AAGO,IAAM,wBAAwB;AAAA,EACnC,CAAC,uBAAuB,GAAG;AAC7B;AAeO,SAAS,YAAY,SAAkC;AAC5D,SAAO;AAAA,IACL,MAAM;AAAA,IACN,SAAS;AAAA,IACT;AAAA,IACA,mBAAmB;AAAA,EACrB;AACF;AAMO,SAAS,wBACd,QACoB;AACpB,SAAO;AAAA,IACL,QAAQ,YAAY,OAAO,OAAO;AAAA,IAClC,OAAO;AAAA,IACP,aAAa;AAAA,IACb,SAAS,OAAO;AAAA,EAClB;AACF;;;ACxEA,SAAS,cAAc;AAOhB,SAAS,oBAAoB,SAAiC;AACnE,SAAO,OAAO,KAAK,KAAK,UAAU,OAAO,GAAG,MAAM,EAAE,SAAS,QAAQ;AACvE;AAEA,SAAS,gBAAgB,KAAqB;AAC5C,QAAM,aAAa,IAAI,QAAQ,MAAM,GAAG,EAAE,QAAQ,MAAM,GAAG;AAC3D,QAAM,OAAO,IAAK,WAAW,SAAS,KAAM;AAC5C,SAAO,aAAa,IAAI,OAAO,GAAG;AACpC;AAEO,SAAS,oBAAoB,QAAgC;AAClE,QAAM,UAAU,OAAO,KAAK;AAC5B,QAAM,OAAO,OAAO,KAAK,gBAAgB,OAAO,GAAG,QAAQ,EAAE,SAAS,MAAM;AAC5E,SAAO,KAAK,MAAM,IAAI;AACxB;","names":[]}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@ampvaleo/x402-hyperliquid-core",
+  "version": "0.1.0",
+  "description": "Types, EIP-712, and encoding for x402 on Hyperliquid HyperCore",
+  "author": "Valeo Protocol",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/valeo-cash/x402-hyperliquid.git",
+    "directory": "packages/core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "viem": "^2.21.54"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}