x402-crypto-derivatives-data 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Duo Data Utilities
+
+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

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# x402-crypto-derivatives-data
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Crypto derivatives data API for AI agents and trading bots: perp funding rates, funding rate history, funding arbitrage, a perp screener, open interest, futures basis, implied volatility, liquidations and order book depth across Bybit, Hyperliquid, dYdX, Gate, Kraken, Bitfinex, Deribit and OKX. $0.003 or $0.005 per call, paid per request with [x402](https://x402.org) (USDC on Base). No API key, no signup.
+
+This is the TypeScript client for https://derivs.duoleads.com. It is also part of [`duo-data-utilities`](https://www.npmjs.com/package/duo-data-utilities) (as `client.derivs`); this package has the derivatives client only.
+
+## Install
+
+```sh
+npm install x402-crypto-derivatives-data viem
+```
+
+`viem` creates the wallet account that pays. Node.js 20 or later.
+
+## Quick start
+
+```ts
+import { privateKeyToAccount } from "viem/accounts";
+import { createClient } from "x402-crypto-derivatives-data";
+
+// Your wallet holds USDC on Base. Read the key from the environment, never a literal.
+const client = createClient({ account: privateKeyToAccount(process.env.PAYER_KEY as `0x${string}`) });
+
+const funding = await client.fundingRates({ coin: "BTC" });                          // $0.003
+const arb = await client.fundingArbitrage({ min_apr: 10, limit: 20 });              // $0.005
+const oi = await client.openInterest({ coin: "ETH" });                              // $0.003
+const snapshot = await client.derivativesSnapshot({ coin: "SOL" });                 // $0.005
+```
+
+Each method sends one GET, pays the 402 challenge with your wallet and resolves to the JSON answer. `client.callWithReceipt(path, params)` also returns the settlement receipt (transaction hash).
+
+## Price guard
+
+Before anything is signed, the client checks the payment requirement: Base USDC only, only to the service's address `0xCD673f7e1daD254347AEab6be0DEFe8b9C6b3A39`, and never above the cap (default $0.005; `maxPriceUsd: 0.003` refuses the $0.005 routes). A refused call signs nothing and throws `PriceGuardError`. The client never retries a paid call on its own.
+
+## Errors and charges
+
+A bad input is a free 400, an unknown coin a free 404, and too few venues answering a 503 that is not charged. Errors throw `DuoApiError` with `code`, `param`, `expected` and `requestId`.
+
+## Routes
+
+<!-- routes:derivs:client. -->
+| Method | Route | Price | MCP tool | What it returns |
+|---|---|---|---|---|
+| `client.fundingRates` | `GET /v1/funding-rates` | $0.003 | `perp_funding_rates` | Perp funding rates by exchange (one coin) |
+| `client.fundingHistory` | `GET /v1/funding-history` | $0.003 | `funding_rate_history` | Funding rate history (one coin, one venue, up to 30 days) |
+| `client.fundingArbitrage` | `GET /v1/funding-arbitrage` | $0.005 | `funding_arbitrage_scan` | Funding arbitrage scanner (all coins) |
+| `client.perpScreener` | `GET /v1/perp-screener` | $0.005 | `perp_screener` | Perp screener (every perpetual, sorted) |
+| `client.openInterest` | `GET /v1/open-interest` | $0.003 | `open_interest` | Open interest by exchange (one coin) |
+| `client.basis` | `GET /v1/basis` | $0.003 | `futures_basis` | Futures basis, term structure and perp premium (one coin) |
+| `client.options` | `GET /v1/options` | $0.003 | `implied_volatility` | Implied volatility, skew and max pain (crypto options) |
+| `client.liquidations` | `GET /v1/liquidations` | $0.003 | `liquidations` | Liquidations (one coin, last 1-24 h) |
+| `client.orderbook` | `GET /v1/orderbook` | $0.003 | `order_book_depth` | Order book depth and slippage (one coin, 8 venues) |
+| `client.derivativesSnapshot` | `GET /v1/derivatives-snapshot` | $0.005 | `derivatives_snapshot` | Crypto derivatives snapshot (one coin, one call) |
+<!-- /routes -->
+
+`DERIVS_ROUTES` holds this table as data (path, MCP tool, price).
+
+## MCP and plain HTTP
+
+The same 10 tools are a paid MCP server at `https://derivs.duoleads.com/mcp` (Streamable HTTP; `tools/list` is free). Every route also works without this package: an unpaid request returns `402 Payment Required` with a `PAYMENT-REQUIRED` header, and any x402 v2 client can pay it.
+
+## Links
+
+- Docs: https://derivs.duoleads.com/docs
+- OpenAPI: https://derivs.duoleads.com/openapi.json
+- Machine-readable index: https://derivs.duoleads.com/llms.txt
+- Terms: https://derivs.duoleads.com/terms
+- Privacy: https://derivs.duoleads.com/privacy
+
+Data only: not investment advice, not a benchmark, not affiliated with any exchange.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/index.cjs

@@ -0,0 +1,313 @@
+"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, {
+  BASE_NETWORK: () => BASE_NETWORK,
+  BASE_USDC_ADDRESS: () => BASE_USDC_ADDRESS,
+  DEFAULT_DERIVS_BASE_URL: () => DEFAULT_DERIVS_BASE_URL,
+  DEFAULT_DERIVS_MAX_PRICE_USD: () => DEFAULT_DERIVS_MAX_PRICE_USD,
+  DERIVS_MCP_URL: () => DERIVS_MCP_URL,
+  DERIVS_ROUTES: () => DERIVS_ROUTES,
+  DuoApiError: () => DuoApiError,
+  PriceGuardError: () => PriceGuardError,
+  SDK_USER_AGENT: () => SDK_USER_AGENT,
+  SDK_VERSION: () => SDK_VERSION,
+  assertDerivsPath: () => assertDerivsPath,
+  buildDerivsQuery: () => buildDerivsQuery,
+  createClient: () => createDerivsClient,
+  createDerivsClient: () => createDerivsClient,
+  createDerivsGeneratedClient: () => createDerivsGeneratedClient,
+  derivsNumber: () => derivsNumber
+});
+module.exports = __toCommonJS(index_exports);
+
+// ../../src/derivs-generated.ts
+var DERIVS_ROUTES = [
+  { path: "/v1/funding-rates", tool: "perp_funding_rates", method: "fundingRates", priceUsd: "0.003", amount: "3000" },
+  { path: "/v1/funding-history", tool: "funding_rate_history", method: "fundingHistory", priceUsd: "0.003", amount: "3000" },
+  { path: "/v1/funding-arbitrage", tool: "funding_arbitrage_scan", method: "fundingArbitrage", priceUsd: "0.005", amount: "5000" },
+  { path: "/v1/perp-screener", tool: "perp_screener", method: "perpScreener", priceUsd: "0.005", amount: "5000" },
+  { path: "/v1/open-interest", tool: "open_interest", method: "openInterest", priceUsd: "0.003", amount: "3000" },
+  { path: "/v1/basis", tool: "futures_basis", method: "basis", priceUsd: "0.003", amount: "3000" },
+  { path: "/v1/options", tool: "implied_volatility", method: "options", priceUsd: "0.003", amount: "3000" },
+  { path: "/v1/liquidations", tool: "liquidations", method: "liquidations", priceUsd: "0.003", amount: "3000" },
+  { path: "/v1/orderbook", tool: "order_book_depth", method: "orderbook", priceUsd: "0.003", amount: "3000" },
+  { path: "/v1/derivatives-snapshot", tool: "derivatives_snapshot", method: "derivativesSnapshot", priceUsd: "0.005", amount: "5000" }
+];
+function createDerivsGeneratedClient(call) {
+  return {
+    fundingRates: (params) => call("/v1/funding-rates", params ?? {}),
+    fundingHistory: (params) => call("/v1/funding-history", params ?? {}),
+    fundingArbitrage: (params) => call("/v1/funding-arbitrage", params ?? {}),
+    perpScreener: (params) => call("/v1/perp-screener", params ?? {}),
+    openInterest: (params) => call("/v1/open-interest", params ?? {}),
+    basis: (params) => call("/v1/basis", params ?? {}),
+    options: (params) => call("/v1/options", params ?? {}),
+    liquidations: (params) => call("/v1/liquidations", params ?? {}),
+    orderbook: (params) => call("/v1/orderbook", params ?? {}),
+    derivativesSnapshot: (params) => call("/v1/derivatives-snapshot", params ?? {})
+  };
+}
+
+// ../../src/errors.ts
+var DuoApiError = class extends Error {
+  /** Error code from the envelope, e.g. `INVALID_PARAM`, or `HTTP_<status>` when there is no envelope. */
+  code;
+  /** The offending query parameter, or `null`. */
+  param;
+  /** The accepted form, or `null`. */
+  expected;
+  /** HTTP status of the response. */
+  status;
+  /** Route path that was called, e.g. `/v1/id/iban`. */
+  route;
+  /** Request id from the envelope's `meta`, when present. */
+  requestId;
+  constructor(init) {
+    super(init.message);
+    this.name = "DuoApiError";
+    this.code = init.code;
+    this.param = init.param ?? null;
+    this.expected = init.expected ?? null;
+    this.status = init.status;
+    this.route = init.route;
+    this.requestId = init.requestId ?? null;
+  }
+};
+var PriceGuardError = class extends Error {
+  /** One entry per refused requirement, e.g. `amount 60000 atomic units ($0.06) is above the maximum $0.05`. */
+  reasons;
+  /** The per-call maximum in effect, in USD. */
+  maxPriceUsd;
+  constructor(reasons, maxPriceUsd) {
+    super(`Refused to pay: ${reasons.join("; ")}. Nothing was signed (maximum $${maxPriceUsd} per call).`);
+    this.name = "PriceGuardError";
+    this.reasons = reasons;
+    this.maxPriceUsd = maxPriceUsd;
+  }
+};
+
+// ../../src/price-guard.ts
+var import_fetch = require("@x402/fetch");
+var BASE_NETWORK = "eip155:8453";
+var BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+var DEFAULT_PAY_TO = "0xCD673f7e1daD254347AEab6be0DEFe8b9C6b3A39";
+function usdToAtomic(usd) {
+  if (!Number.isFinite(usd) || usd <= 0) throw new RangeError(`maxPriceUsd must be a positive number, got ${usd}`);
+  const atomic = BigInt(Math.floor(usd * 1e6 + 1e-6));
+  if (atomic < 1n) throw new RangeError("maxPriceUsd must be at least 0.000001 (one USDC base unit)");
+  return atomic;
+}
+function formatUsd(atomic) {
+  const whole = atomic / 1000000n;
+  const fraction = (atomic % 1000000n).toString().padStart(6, "0").replace(/0+$/, "").padEnd(2, "0");
+  return `$${whole}.${fraction}`;
+}
+function requirementProblem(requirement, maxAtomic, payTo = DEFAULT_PAY_TO) {
+  if (requirement.scheme !== "exact") return `scheme ${JSON.stringify(requirement.scheme ?? null)} is not "exact"`;
+  if (requirement.network !== BASE_NETWORK) {
+    return `network ${JSON.stringify(requirement.network ?? null)} is not ${BASE_NETWORK} (Base)`;
+  }
+  if (typeof requirement.asset !== "string" || requirement.asset.toLowerCase() !== BASE_USDC_ADDRESS.toLowerCase()) {
+    return `asset ${JSON.stringify(requirement.asset ?? null)} is not Base USDC (${BASE_USDC_ADDRESS})`;
+  }
+  if (typeof requirement.amount !== "string" || !/^[0-9]+$/.test(requirement.amount)) {
+    return `amount ${JSON.stringify(requirement.amount ?? null)} is not an integer in atomic USDC units`;
+  }
+  if (payTo !== null && (typeof requirement.payTo !== "string" || requirement.payTo.toLowerCase() !== payTo.toLowerCase())) {
+    return `payTo ${JSON.stringify(requirement.payTo ?? null)} is not the expected payee ${payTo}`;
+  }
+  const amount = BigInt(requirement.amount);
+  if (amount === 0n) return "amount is zero";
+  if (amount > maxAtomic) {
+    return `amount ${requirement.amount} atomic units (${formatUsd(amount)}) is above the maximum ${formatUsd(maxAtomic)}`;
+  }
+  return null;
+}
+var decoder = new import_fetch.x402HTTPClient(new import_fetch.x402Client());
+function guardChallenges(transport, maxAtomic, maxPriceUsd, payTo = DEFAULT_PAY_TO) {
+  return async (input, init) => {
+    const request = new Request(input, init);
+    const response = await transport(request);
+    const isPaidRetry = request.headers.has("payment-signature") || request.headers.has("x-payment");
+    if (response.status !== 402 || isPaidRetry) return response;
+    let required;
+    try {
+      let body;
+      if (!response.headers.get("PAYMENT-REQUIRED")) body = await response.clone().json().catch(() => void 0);
+      required = decoder.getPaymentRequiredResponse((name) => response.headers.get(name), body);
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new PriceGuardError([`the payment requirements could not be read: ${reason}`], maxPriceUsd);
+    }
+    const reasons = [];
+    if (required.x402Version !== 2) reasons.push(`x402Version ${String(required.x402Version)} is not 2`);
+    const options = Array.isArray(required.accepts) ? required.accepts : [];
+    const problems = options.map((option) => requirementProblem(option, maxAtomic, payTo));
+    if (options.length === 0) reasons.push("the challenge offers no payment option");
+    else if (problems.every((problem) => problem !== null)) reasons.push(...problems);
+    if (reasons.length > 0) throw new PriceGuardError(reasons, maxPriceUsd);
+    return response;
+  };
+}
+function guardPolicy(maxAtomic, payTo = DEFAULT_PAY_TO) {
+  return (_version, requirements) => requirements.filter((requirement) => requirementProblem(requirement, maxAtomic, payTo) === null);
+}
+
+// ../../src/transport.ts
+var import_fetch2 = require("@x402/fetch");
+var import_client = require("@x402/evm/exact/client");
+function canSetUserAgent() {
+  const scope = globalThis;
+  return typeof scope.document === "undefined" && typeof scope.WorkerGlobalScope === "undefined";
+}
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+function normaliseBaseUrl(raw) {
+  const url = new URL(raw);
+  const plainLoopback = url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+  if (url.protocol !== "https:" && !plainLoopback) {
+    throw new TypeError(`baseUrl must use https (plain http is only allowed for localhost): ${raw}`);
+  }
+  if (url.search || url.hash) throw new TypeError("baseUrl must not contain a query or a fragment");
+  return `${url.origin}${url.pathname.replace(/\/+$/, "")}`;
+}
+function buildPayingFetch(account, maxAtomic, maxPriceUsd, payTo) {
+  return (0, import_fetch2.wrapFetchWithPaymentFromConfig)(guardChallenges(globalThis.fetch, maxAtomic, maxPriceUsd, payTo), {
+    schemes: [{ network: BASE_NETWORK, client: new import_client.ExactEvmScheme(account) }],
+    policies: [guardPolicy(maxAtomic, payTo)],
+    // A second, independent cap in the payment layer, in USD for the default USDC asset.
+    spendControls: { maxAmountPerPayment: maxPriceUsd }
+  });
+}
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+function receiptOf(response) {
+  const header = response.headers.get("payment-response");
+  if (!header) return null;
+  try {
+    return (0, import_fetch2.decodePaymentResponseHeader)(header);
+  } catch {
+    return null;
+  }
+}
+
+// ../../src/version.ts
+var SDK_VERSION = true ? "0.3.0" : "0.0.0-dev";
+var SDK_USER_AGENT = `${true ? "x402-crypto-derivatives-data" : "duo-data-utilities"}-js/${SDK_VERSION} (+https://github.com/hiesem/duo-data-utilities)`;
+
+// ../../src/derivs.ts
+var DEFAULT_DERIVS_BASE_URL = "https://derivs.duoleads.com";
+var DEFAULT_DERIVS_MAX_PRICE_USD = 5e-3;
+var DERIVS_MCP_URL = "https://derivs.duoleads.com/mcp";
+var DERIVS_PATH = /^\/v1\/[a-z0-9-]+$/;
+function assertDerivsPath(path) {
+  if (!DERIVS_PATH.test(path)) throw new TypeError(`not a derivs route path: ${JSON.stringify(path)} (expected /v1/<name>)`);
+}
+function derivsNumber(name, value) {
+  if (!Number.isFinite(value)) throw new TypeError(`parameter ${name} must be a finite number`);
+  if (Number.isInteger(value)) return BigInt(value).toString();
+  return value.toFixed(8).replace(/0+$/, "").replace(/\.$/, "");
+}
+function buildDerivsQuery(params) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null) continue;
+    if (typeof value === "number") search.append(key, derivsNumber(key, value));
+    else if (typeof value === "string" || typeof value === "boolean") search.append(key, String(value));
+    else throw new TypeError(`parameter ${key} must be a string, number or boolean`);
+  }
+  return search.toString();
+}
+function derivsError(path, status, ok, body) {
+  const requestId = isRecord(body) && typeof body.request_id === "string" ? body.request_id : null;
+  if (isRecord(body) && isRecord(body.error)) {
+    const error = body.error;
+    return new DuoApiError({
+      code: typeof error.code === "string" ? error.code : "UNKNOWN_ERROR",
+      message: typeof error.message === "string" ? error.message : `${path} failed with HTTP ${status}`,
+      param: typeof error.param === "string" ? error.param : null,
+      expected: typeof error.expected === "string" ? error.expected : null,
+      status,
+      route: path,
+      requestId
+    });
+  }
+  if (status === 402) {
+    return new DuoApiError({ code: "PAYMENT_REQUIRED", message: "the payment was not accepted (HTTP 402)", status, route: path, requestId });
+  }
+  if (ok) {
+    return new DuoApiError({ code: "INVALID_RESPONSE", message: `${path} did not return a JSON object (HTTP ${status})`, status, route: path, requestId });
+  }
+  return new DuoApiError({ code: `HTTP_${status}`, message: `${path} failed with HTTP ${status}`, status, route: path, requestId });
+}
+function createDerivsClient(options = {}) {
+  if (options.account !== void 0 === (options.fetch !== void 0)) {
+    throw new TypeError("createDerivsClient needs exactly one of `account` (pays with your wallet) or `fetch` (a fetch that already pays)");
+  }
+  const baseUrl = normaliseBaseUrl(options.baseUrl ?? DEFAULT_DERIVS_BASE_URL);
+  const maxPriceUsd = options.maxPriceUsd ?? DEFAULT_DERIVS_MAX_PRICE_USD;
+  const userAgent = options.userAgent ?? SDK_USER_AGENT;
+  if (/[\r\n]/.test(userAgent)) throw new TypeError("userAgent must not contain line breaks");
+  const maxAtomic = usdToAtomic(maxPriceUsd);
+  const payTo = options.payTo === void 0 ? DEFAULT_PAY_TO : options.payTo;
+  const payingFetch = options.account !== void 0 ? buildPayingFetch(options.account, maxAtomic, maxPriceUsd, payTo) : options.fetch;
+  const callPaid = async (path, params = {}) => {
+    assertDerivsPath(path);
+    const query = buildDerivsQuery(params);
+    const headers = { accept: "application/json" };
+    if (canSetUserAgent() && userAgent) headers["user-agent"] = userAgent;
+    const response = await payingFetch(`${baseUrl}${path}${query ? `?${query}` : ""}`, { method: "GET", headers });
+    const body = parseJson(await response.text());
+    if (response.ok && isRecord(body) && !("error" in body)) return { data: body, receipt: receiptOf(response) };
+    throw derivsError(path, response.status, response.ok, body);
+  };
+  const call = async (path, params) => (await callPaid(path, params)).data;
+  return {
+    ...createDerivsGeneratedClient(call),
+    call: (path, params) => call(path, params ?? {}),
+    callWithReceipt: (path, params) => callPaid(path, params ?? {})
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BASE_NETWORK,
+  BASE_USDC_ADDRESS,
+  DEFAULT_DERIVS_BASE_URL,
+  DEFAULT_DERIVS_MAX_PRICE_USD,
+  DERIVS_MCP_URL,
+  DERIVS_ROUTES,
+  DuoApiError,
+  PriceGuardError,
+  SDK_USER_AGENT,
+  SDK_VERSION,
+  assertDerivsPath,
+  buildDerivsQuery,
+  createClient,
+  createDerivsClient,
+  createDerivsGeneratedClient,
+  derivsNumber
+});