Current section
Files
Jump to
Current section
Files
priv/specs/json/output/exchange_v3.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "exchange_v3.json",
"title": "CCXT Exchange Extraction Output",
"description": "Per-exchange extraction output from ccxt_extract. Contains everything CCXT knows about a single exchange, organized into two layers: runtime values (QuickBEAM) and structural AST (OXC). Schema 3.0.0 (Task 117, breaking) replaces runtime.markets with the compact runtime.symbols_index derivation and drops structure.parse_methods + structure.ws_methods (extractors retained; discovery files still written for internal Phase 12 / Phase 15 consumers). See SCHEMA.md migration notes.",
"type": "object",
"required": ["schema_version", "extracted_at", "ccxt_version", "exchange", "runtime", "structure", "_provenance"],
"additionalProperties": false,
"properties": {
"schema_version": {
"const": "3.0.0",
"description": "Schema version. Consumers should check this before parsing."
},
"extracted_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of extraction."
},
"ccxt_version": {
"type": "string",
"description": "CCXT npm package version used for extraction."
},
"exchange": {
"$ref": "#/$defs/ExchangeMeta"
},
"runtime": {
"$ref": "#/$defs/RuntimeData"
},
"structure": {
"$ref": "#/$defs/StructureData"
},
"_provenance": {
"$ref": "#/$defs/ProvenanceMap",
"description": "Required per-path provenance map (raw/derived/override). Required and non-null since schema 2.0.0 (Task 61c)."
}
},
"$defs": {
"ProvenanceMap": {
"type": "object",
"description": "Flat map keyed by RFC 6901 JSON Pointer strings into the payload. Values tag the source tier: raw (discovery passthrough), derived (assembly-time computation), override (priv/overrides/<id>.json).",
"propertyNames": {
"type": "string",
"pattern": "^/"
},
"additionalProperties": {
"type": "string",
"enum": ["raw", "derived", "override"]
}
},
"ExchangeMeta": {
"type": "object",
"description": "Exchange identity and metadata from CCXT runtime.",
"required": ["id", "name", "alias"],
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "CCXT exchange identifier (e.g., 'binance', 'kraken')."
},
"name": {
"type": "string",
"description": "Human-readable exchange name."
},
"certified": {
"type": "boolean",
"description": "Whether the exchange is CCXT-certified."
},
"pro": {
"type": "boolean",
"description": "Whether the exchange has WebSocket (pro) support."
},
"version": {
"type": ["string", "null"],
"description": "Exchange API version string."
},
"country": {
"type": "array",
"items": { "type": "string" },
"description": "ISO country codes where the exchange is based."
},
"alias": {
"type": "boolean",
"description": "True if this is a re-brand alias (e.g., huobi -> htx)."
},
"referral": {
"oneOf": [
{ "type": "null" },
{ "$ref": "#/$defs/Referral" }
],
"description": "Referral URL and discount, if any."
},
"tier": {
"type": "string",
"enum": ["tier1", "tier2", "tier3", "dex", "unclassified"],
"description": "Priority tier for this project — hand-curated in priv/priority_tiers.json, not extracted from CCXT. tier1/tier2/dex are the buckets we commit to deriving recipes for; tier3 and unclassified still get full raw extraction."
}
}
},
"Referral": {
"type": "object",
"required": ["url"],
"additionalProperties": false,
"properties": {
"url": { "type": "string" },
"discount": { "type": ["number", "null"] }
}
},
"RuntimeData": {
"type": "object",
"description": "Runtime values extracted via QuickBEAM JavaScript execution. Layer 1: what an exchange IS (configuration, capabilities, markets).",
"required": ["describe", "symbols_index", "symbol_patterns", "url_templates", "testnet_urls"],
"additionalProperties": false,
"properties": {
"describe": {
"oneOf": [
{ "type": "null" },
{ "type": "object", "additionalProperties": true }
],
"description": "Complete describe() output from CCXT runtime. Contains all configuration: api endpoints, has capabilities, fees, limits, urls, exceptions, features, timeframes, requiredCredentials, etc. May contain sentinel strings: '__undefined' (JS undefined values), '__function:<ClassName>' (JS function references with resolved CCXT error class names, e.g. '__function:ExchangeError'). Null for alias exchanges or when no usable describe data was assembled; check pipeline integrity stats to distinguish source gaps from expected nulls."
},
"symbols_index": {
"oneOf": [
{ "type": "null" },
{ "$ref": "#/$defs/SymbolsIndex" }
],
"description": "Derived per-symbol spot/swap classification from loadMarkets(). Introduced at schema 3.0.0 (Task 117) as the compact replacement for the full runtime.markets snapshot. Consumers needing per-market price, precision, fees, limits, or exchange-native ids must call loadMarkets() at runtime — that was the only drift-safe path anyway. Null for alias exchanges, exchanges without cached market data, or when no usable markets data was assembled."
},
"symbol_patterns": {
"oneOf": [
{ "type": "null" },
{ "$ref": "#/$defs/SymbolPatterns" }
],
"description": "Derived symbol formatting patterns per market type. Consumers use these rules for symbol conversion (unified <-> exchange-native). Null when no market data is available."
},
"url_templates": {
"oneOf": [
{ "type": "null" },
{ "$ref": "#/$defs/UrlTemplates" }
],
"description": "URL templates per API section, showing base URL, sample path, and fully resolved URL from sign(). Consumers derive path prefixes injected by sign() (e.g., OKX's /api/v5/, Gate's /spot/). Null for alias exchanges or when sign() fails for all sections."
},
"testnet_urls": {
"$ref": "#/$defs/TestnetUrls",
"description": "Derived testnet / sandbox URL catalog with {hostname} placeholders pre-resolved. See $defs/TestnetUrls for pattern classification."
}
}
},
"TestnetUrls": {
"type": "object",
"description": "Testnet / sandbox URL catalog derived from describe.urls.test + describe.options.sandboxMode. Promotes the raw testnet signals out of the opaque runtime.describe blob so consumers read one canonical shape. Introduced at schema 2.4.0 (Task 100).",
"required": ["pattern", "urls", "sandbox_flag_field", "unresolved_reason"],
"additionalProperties": false,
"properties": {
"pattern": {
"type": "string",
"enum": ["separate_host", "sandbox_flag", "none"],
"description": "Classification: 'separate_host' when describe.urls.test is non-empty; 'sandbox_flag' when only describe.options.sandboxMode is present; 'none' when neither is present."
},
"urls": {
"oneOf": [
{ "type": "null" },
{ "type": "object", "additionalProperties": true }
],
"description": "Testnet URL map from describe.urls.test with {hostname} substitutions resolved. Shape preserved from CCXT (flat section map OR nested host → section map). Non-null only when pattern == 'separate_host'."
},
"sandbox_flag_field": {
"oneOf": [
{ "type": "null" },
{ "type": "string" }
],
"description": "Name of the describe.options flag used to switch to sandbox mode (currently always 'sandboxMode' when present). Populated independently of pattern — may coexist with 'separate_host' (okx uses both a same-host URL AND a flag)."
},
"unresolved_reason": {
"oneOf": [
{ "type": "null" },
{ "type": "string", "enum": ["no_testnet_data"] }
],
"description": "Non-null only when pattern == 'none'. Explains why no testnet data was derived."
}
}
},
"SymbolsIndex": {
"type": "object",
"description": "Compact per-symbol spot/swap classification derived from loadMarkets(). Keys are CCXT unified symbols (e.g. 'BTC/USDT', 'BTC/USDT:USDT'). Introduced at schema 3.0.0 (Task 117) as the drift-safe replacement for the full runtime.markets snapshot. Consumers derive market_count via map size; for price/precision/fees/limits/info call loadMarkets() at runtime.",
"additionalProperties": {
"type": "object",
"required": ["spot", "swap"],
"additionalProperties": false,
"properties": {
"spot": {
"type": "boolean",
"description": "True when the source market carries spot == true or type == 'spot'."
},
"swap": {
"type": "boolean",
"description": "True when the source market carries swap == true or type == 'swap'."
}
}
}
},
"SymbolPatterns": {
"type": "object",
"description": "Symbol formatting patterns derived from market data. Keys are market types ('spot', 'swap', 'future', 'option') mapping to per-type pattern analysis, plus 'currency_aliases' from describe().commonCurrencies.",
"required": ["currency_aliases"],
"properties": {
"spot": { "$ref": "#/$defs/SymbolPatternEntry" },
"swap": { "$ref": "#/$defs/SymbolPatternEntry" },
"future": { "$ref": "#/$defs/SymbolPatternEntry" },
"option": { "$ref": "#/$defs/SymbolPatternEntry" },
"currency_aliases": {
"type": "object",
"additionalProperties": { "type": "string" },
"description": "Exchange-native currency code -> CCXT unified code mapping from describe().commonCurrencies (e.g., 'XXBT' -> 'BTC')."
}
},
"additionalProperties": false
},
"SymbolPatternEntry": {
"type": "object",
"description": "Symbol formatting pattern analysis for a single market type.",
"required": ["id_structure", "separator", "case", "suffix", "sample_count", "anomaly_count", "anomalies", "examples"],
"additionalProperties": false,
"properties": {
"id_structure": {
"type": ["string", "null"],
"description": "How the exchange ID is composed from currency codes: 'baseId_quoteId' (most common), 'quoteId_baseId', 'baseId_only', 'numeric', or 'opaque'. Null if no dominant pattern (below 80% threshold)."
},
"separator": {
"type": ["string", "null"],
"description": "Character between currency codes in the ID: '' (concatenated), '-' (dash), '_' (underscore). Null if no dominant pattern."
},
"case": {
"type": ["string", "null"],
"enum": ["upper", "lower", "mixed", null],
"description": "Case convention of the exchange ID. Null if no dominant pattern."
},
"suffix": {
"type": ["string", "null"],
"description": "Constant suffix appended after the currency pair (e.g., '-SWAP', '-PERPETUAL', 'M'). Null if no suffix detected."
},
"sample_count": {
"type": "integer",
"description": "Number of markets analyzed for this type."
},
"anomaly_count": {
"type": "integer",
"description": "Number of markets that don't match the dominant pattern."
},
"anomalies": {
"type": "array",
"items": { "type": "string" },
"description": "Exchange IDs that don't match the dominant pattern (max 50). Consumers should use direct symbol->id lookup for these."
},
"examples": {
"type": "array",
"items": {
"type": "object",
"required": ["symbol", "id", "baseId", "quoteId"],
"additionalProperties": false,
"properties": {
"symbol": { "type": "string" },
"id": { "type": "string" },
"baseId": { "type": "string" },
"quoteId": { "type": "string" }
}
},
"description": "Representative sample markets (max 3) showing the symbol-to-id mapping."
}
}
},
"UrlTemplates": {
"type": "object",
"description": "URL templates per API section. Keys are dot-joined section paths (e.g., 'public', 'private', 'public.spot', 'private.delivery'). Each entry records the raw sign() probe: inputs (api_param, http_method, sample_path) and output (resolved_url), plus a derived url_prefix when provably correct.",
"additionalProperties": { "$ref": "#/$defs/UrlTemplateEntry" }
},
"UrlTemplateEntry": {
"type": "object",
"description": "Raw sign() probe for a single API section. Records what was passed to sign() and what it returned. url_prefix is derived (resolved_url minus trailing sample_path) only when provably correct — null for suffix-mutation exchanges (bit2c, lbank, zonda) and sign() failures.",
"required": ["api_param", "http_method", "sample_path", "resolved_url", "url_prefix"],
"additionalProperties": false,
"properties": {
"api_param": {
"oneOf": [
{ "type": "string" },
{ "type": "array", "items": { "type": "string" } }
],
"description": "Section identifier passed to sign(). String for flat sections ('public'), array for multi-level (['public', 'spot'])."
},
"http_method": {
"type": "string",
"description": "HTTP method of the sampled endpoint passed to sign() (GET, POST, PUT, DELETE, PATCH)."
},
"sample_path": {
"type": "string",
"description": "First endpoint path from this API section (used as sign() input)."
},
"resolved_url": {
"type": ["string", "null"],
"description": "Full URL returned by sign(). Null if sign() threw (e.g., private sections without credentials, or sections missing from urls.api)."
},
"url_prefix": {
"type": ["string", "null"],
"description": "Derived: resolved_url with sample_path stripped from the end. Null when resolved_url doesn't cleanly end with sample_path (suffix-mutation exchanges like bit2c, lbank, zonda) or when sign() failed. Consumers use this as the full URL prefix for the section."
}
}
},
"StructureData": {
"type": "object",
"description": "Structural data extracted via OXC TypeScript AST parsing. Layer 2: what an exchange DOES (code structure, method bodies).",
"required": ["class_info", "methods", "sign_method", "authenticated_sections", "sign_recipe", "handle_errors", "interface_signatures", "pagination", "overrides", "unified_endpoints", "request_defaults"],
"additionalProperties": false,
"properties": {
"class_info": {
"oneOf": [
{ "type": "null" },
{ "$ref": "#/$defs/ClassInfo" }
],
"description": "Class hierarchy information. Null for alias exchanges without class entries or when no usable class info was assembled; check pipeline integrity stats to distinguish source gaps from expected nulls."
},
"methods": {
"oneOf": [
{ "type": "null" },
{ "$ref": "#/$defs/MethodInventory" }
],
"description": "Method signature inventory (no AST bodies). Null for alias exchanges or when no usable method inventory was assembled; check pipeline integrity stats to distinguish source gaps from expected nulls."
},
"sign_method": {
"oneOf": [
{ "type": "null" },
{ "$ref": "#/$defs/MethodAST" }
],
"description": "The sign() method AST for request authentication. Null if the exchange has no sign() method or is an alias."
},
"authenticated_sections": {
"oneOf": [
{ "type": "null" },
{ "type": "array", "items": { "type": "string" } }
],
"description": "API sections proven to require authentication via checkRequiredCredentials() gates in sign() AST. Handles api === 'X' and api[N] === 'X' patterns. Sorted. Null when sign() absent; empty list when sign() exists but no checkRequiredCredentials() gates found. Some exchanges authenticate without checkRequiredCredentials() — use sign_method AST for broader auth detection."
},
"sign_recipe": {
"type": "object",
"additionalProperties": { "$ref": "#/$defs/SignRecipeRecord" },
"description": "Map of section name -> SignRecipeRecord. Keys mirror structure.authenticated_sections (contract-test invariant sign_recipe_keys_match_auth_sections enforces parity). Empty map when sign_method is null or no authenticated sections were detected. Scaffolded in schema 2.2.0; Task 64 emits all-null records with unresolved_reason = \"not_yet_derived\". Tasks 65–69 populate derivation fields incrementally. Standalone copy at priv/schema/sign_recipe_v1.json (must stay in sync)."
},
"handle_errors": {
"oneOf": [
{ "type": "null" },
{ "$ref": "#/$defs/HandleErrorsData" }
],
"description": "The handleErrors() method AST plus exception mappings. Null if the exchange has no handleErrors(), is an alias, or no usable handleErrors data was assembled; check pipeline integrity stats to distinguish source gaps from expected nulls."
},
"interface_signatures": {
"oneOf": [
{ "type": "null" },
{
"type": "object",
"additionalProperties": { "$ref": "#/$defs/InterfaceSignature" }
}
],
"description": "Map of API method name -> InterfaceSignature from abstract/*.ts interface declarations. These are the generated per-exchange typed endpoint methods (e.g., publicGetTicker, privatePostOrder). Null for alias exchanges, exchanges without abstract files, or when no usable data was assembled; check pipeline integrity stats to distinguish source gaps from expected nulls."
},
"pagination": {
"oneOf": [
{ "type": "null" },
{
"type": "object",
"properties": {
"_unresolved": {
"type": "array",
"items": { "$ref": "#/$defs/PaginationEntry" },
"description": "Pagination calls where the target method name is a runtime variable (not a string literal). Each entry has target_method: null and containing_method set to the method body where the call was found."
}
},
"additionalProperties": {
"type": "array",
"items": { "$ref": "#/$defs/PaginationEntry" }
}
}
],
"description": "Map of target method name -> [PaginationEntry] showing which methods use pagination and what strategy. Values are always arrays (multiple entries when branch-dependent variants exist, e.g. coinbase fetchAccounts V2/V3). Optional _unresolved key holds entries with variable method names. Null for exchanges without pagination calls or when no usable pagination data was assembled."
},
"overrides": {
"oneOf": [
{ "type": "null" },
{ "$ref": "#/$defs/OverridesData" }
],
"description": "Method override analysis for derived exchanges. Null for root exchanges (those extending Exchange directly) or when no usable override data was assembled; check pipeline integrity stats to distinguish source gaps from expected nulls."
},
"unified_endpoints": {
"oneOf": [
{ "type": "null" },
{
"type": "object",
"additionalProperties": {
"type": "array",
"items": { "type": "string" }
}
}
],
"description": "Map of unified method name -> list of interface method names called within that method body (e.g., 'fetchTicker' -> ['publicGetV5MarketTickers']). Multiple entries when the method branches by market type or API version. Alias/derived exchanges inherit parent mappings when they have no own unified endpoints. Null when no unified endpoint mappings were found (own or inherited)."
},
"request_defaults": {
"oneOf": [
{ "type": "null" },
{ "$ref": "#/$defs/RequestDefaults" }
],
"description": "Map of method name -> per-key default request body entries extracted from literal ObjectExpressions that flow into this.<httpVerb>() calls. Per the Honesty Rule: resolvable primitives emit kind='literal' with value set; non-literal expressions emit kind='unresolved' with a closed-vocabulary reason tag (the value is null). Methods with no HTTP call, pure delegation, empty literal body, or divergent multiple-call-site bodies are silently absent. Null when no methods produced extractable defaults."
}
}
},
"RequestDefaults": {
"type": "object",
"description": "Map of method name -> (map of property key -> RequestDefaultsEntry). Keys are method names as they appear in the TypeScript class (e.g., 'fetchTime'). Per-property keys preserve the exchange's own string-literal keys verbatim; computed keys surface as the synthetic key '_computed'.",
"additionalProperties": {
"type": "object",
"additionalProperties": { "$ref": "#/$defs/RequestDefaultsEntry" }
}
},
"RequestDefaultsEntry": {
"type": "object",
"required": ["value", "kind", "reason"],
"additionalProperties": false,
"properties": {
"value": {
"description": "The resolved literal value (string, number, boolean, null, nested literal object, array of literals) when kind='literal'; always null when kind='unresolved'."
},
"kind": {
"type": "string",
"enum": ["literal", "unresolved"],
"description": "'literal' means the value is a fully provable primitive or nested literal; 'unresolved' means the AST expression is non-literal and the value is null."
},
"reason": {
"oneOf": [
{ "type": "null" },
{
"type": "string",
"enum": ["conditional_value", "identifier_reference", "dynamic_construction", "computed_key", "spread_elaboration"]
}
],
"description": "Null when kind='literal'. Otherwise a closed-vocabulary tag: 'conditional_value' (ternary / logical expression), 'identifier_reference' (variable or member access), 'dynamic_construction' (call, binary, template literal, partially-literal object/array), 'computed_key' (key was a computed expression), 'spread_elaboration' (reserved for future spread tracking)."
}
}
},
"SignRecipeRecord": {
"type": "object",
"additionalProperties": false,
"required": ["crypto_op", "canonical_string", "signature_placement", "auth_headers", "nonce", "pre_sign_transforms", "unresolved_reason", "patch_count"],
"description": "Declarative per-section signing recipe. Authoritative copy of priv/schema/sign_recipe_v1.json (kept in lockstep). See CcxtExtract.SignRecipe moduledoc and SCHEMA.md § Signing Recipe. All derivation fields are nullable: Task 64 ships every record with null derivation fields + unresolved_reason = \"not_yet_derived\". Tasks 65–69 populate fields incrementally.",
"properties": {
"crypto_op": {
"oneOf": [{ "type": "null" }, { "$ref": "#/$defs/SignRecipeCryptoOp" }],
"description": "Hash / signature algorithm. Populated by Task 65."
},
"canonical_string": {
"oneOf": [
{ "type": "null" },
{
"type": "object",
"minProperties": 1,
"additionalProperties": false,
"patternProperties": {
"^(GET|POST|PUT|DELETE|PATCH|\\*)$": { "$ref": "#/$defs/SignRecipeCanonicalString" }
}
}
],
"description": "Per-verb map of canonical-string records. Keys are HTTP verb names (GET|POST|PUT|DELETE|PATCH) when sign() branches on method, or the sentinel `*` when every verb shares the same canonical string. A single section may mix families (e.g. GET = hmac_simple, POST = hmac_with_body). Populated by Tasks 66a (HMAC-simple entries) / 66b (HMAC-with-body entries)."
},
"signature_placement": {
"oneOf": [{ "type": "null" }, { "$ref": "#/$defs/SignRecipeSignaturePlacement" }],
"description": "Where the final signature is attached to the request. Populated by Task 65."
},
"auth_headers": {
"oneOf": [
{ "type": "null" },
{ "type": "array", "items": { "$ref": "#/$defs/SignRecipeAuthHeader" } }
],
"description": "Ordered list of auth-related headers (excluding the signature header itself — see signature_placement). Populated by Task 67."
},
"nonce": {
"oneOf": [{ "type": "null" }, { "$ref": "#/$defs/SignRecipeNonce" }],
"description": "Timestamp / nonce source and wire format. Populated by Task 67."
},
"pre_sign_transforms": {
"oneOf": [
{ "type": "null" },
{ "type": "array", "items": { "$ref": "#/$defs/SignRecipePreSignTransform" } }
],
"description": "Ordered transforms applied to the canonical string, body, or resulting signature before going on the wire. Populated by Task 68."
},
"unresolved_reason": {
"oneOf": [
{ "type": "null" },
{ "type": "string", "enum": ["not_yet_derived", "custom_signing_family", "ambiguous_ast", "no_sign_method"] }
],
"description": "Closed-vocabulary reason when derivation fields are null. \"not_yet_derived\" is the scaffold default. Must be null only when every derivation field above is non-null (enforced by Task 69)."
},
"patch_count": {
"type": "integer",
"minimum": 0,
"description": "Three-Strikes counter (see CLAUDE.md). At 3, migrate the recipe to priv/overrides/<id>.json rather than continuing to stretch derivation."
}
}
},
"SignRecipeCryptoOp": {
"type": "object",
"additionalProperties": false,
"required": ["algo"],
"properties": {
"algo": {
"type": "string",
"enum": ["hmac_sha256", "hmac_sha512", "hmac_sha384", "ed25519", "rsa", "custom"]
},
"reason": {
"type": "string",
"minLength": 1,
"description": "Optional rationale; required only when algo = \"custom\"."
}
}
},
"SignRecipeCanonicalString": {
"type": "object",
"additionalProperties": false,
"required": ["family", "components", "encoding"],
"properties": {
"family": {
"type": "string",
"enum": ["hmac_simple", "hmac_with_body", "jwt", "custom"]
},
"components": {
"type": "array",
"items": { "$ref": "#/$defs/SignRecipeCanonicalComponent" }
},
"encoding": {
"type": "string",
"enum": ["url_encoded", "json", "raw"]
}
}
},
"SignRecipeCanonicalComponent": {
"type": "object",
"additionalProperties": false,
"required": ["source"],
"properties": {
"source": {
"type": "string",
"enum": ["timestamp", "api_key", "recv_window", "method", "path", "query", "body", "literal"]
},
"value": {
"type": "string",
"description": "Required iff source = \"literal\"; absent otherwise."
}
}
},
"SignRecipeSignaturePlacement": {
"type": "object",
"additionalProperties": false,
"required": ["location", "key"],
"properties": {
"location": {
"type": "string",
"enum": ["header", "query", "body"]
},
"key": {
"type": "string",
"minLength": 1
}
}
},
"SignRecipeAuthHeader": {
"type": "object",
"additionalProperties": false,
"required": ["name", "source"],
"properties": {
"name": { "type": "string", "minLength": 1 },
"source": {
"type": "string",
"enum": ["api_key", "passphrase", "timestamp", "signature", "recv_window", "literal"]
},
"value": {
"type": "string",
"description": "Required iff source = \"literal\"; absent otherwise."
}
}
},
"SignRecipeNonce": {
"type": "object",
"additionalProperties": false,
"required": ["source", "format"],
"properties": {
"source": {
"type": "string",
"enum": ["timestamp_ms", "timestamp_sec", "timestamp_us", "timestamp_ns", "monotonic", "exchange_supplied"]
},
"format": {
"type": "string",
"enum": ["integer", "iso8601", "hex", "string"]
}
}
},
"SignRecipePreSignTransform": {
"type": "object",
"additionalProperties": false,
"required": ["op", "target"],
"properties": {
"op": {
"type": "string",
"enum": ["hex_encode", "base64_encode", "lowercase", "url_encode", "json_encode"]
},
"target": {
"type": "string",
"enum": ["signature", "body", "canonical_string"]
}
}
},
"ClassInfo": {
"type": "object",
"required": ["rest"],
"additionalProperties": false,
"properties": {
"rest": {
"$ref": "#/$defs/ClassEntry",
"description": "REST class information."
},
"ws": {
"oneOf": [
{ "type": "null" },
{ "$ref": "#/$defs/ClassEntry" }
],
"description": "WS class information. Null if no WebSocket implementation."
}
}
},
"ClassEntry": {
"type": "object",
"required": ["node_key", "class_name", "extends_resolved", "parent_key", "file", "method_count"],
"additionalProperties": false,
"properties": {
"node_key": {
"type": "string",
"description": "Unique identity: 'rest:<id>' or 'ws:<id>'."
},
"class_name": {
"type": "string",
"description": "TypeScript class name."
},
"id": {
"type": "string",
"description": "Exchange identifier (same as class_name for most exchanges)."
},
"type": {
"type": "string",
"enum": ["rest", "ws"],
"description": "Class type: 'rest' for REST exchange, 'ws' for WebSocket exchange."
},
"extends_raw": {
"type": "string",
"description": "Raw extends value from AST (may be an import alias, e.g., 'binanceRest')."
},
"extends_resolved": {
"type": "string",
"description": "Resolved parent class name (e.g., 'binance' after alias resolution)."
},
"parent_key": {
"type": "string",
"description": "Parent node_key (e.g., 'Exchange', 'rest:binance')."
},
"file": {
"type": "string",
"description": "Source filename (e.g., 'binance.ts')."
},
"method_count": {
"type": "integer",
"description": "Number of methods defined in this class."
},
"methods": {
"type": "array",
"items": { "type": "string" },
"description": "List of method names defined in this class."
},
"method_details": {
"type": "array",
"items": { "$ref": "#/$defs/MethodDetail" },
"description": "Per-method metadata (name, async, param count, statement count)."
}
}
},
"MethodDetail": {
"type": "object",
"required": ["name", "async", "params", "statements"],
"additionalProperties": false,
"properties": {
"name": { "type": "string" },
"async": { "type": "boolean" },
"params": { "type": "integer", "description": "Parameter count." },
"statements": { "type": "integer", "description": "Statement count in method body." }
}
},
"MethodInventory": {
"type": "object",
"required": ["rest"],
"additionalProperties": false,
"properties": {
"rest": {
"type": "array",
"items": { "$ref": "#/$defs/MethodSignature" },
"description": "REST method signatures."
},
"ws": {
"oneOf": [
{ "type": "null" },
{
"type": "array",
"items": { "$ref": "#/$defs/MethodSignature" }
}
],
"description": "WS method signatures. Null if no WebSocket implementation."
}
}
},
"MethodSignature": {
"type": "object",
"description": "Method signature without AST body.",
"required": ["name", "async", "params", "return_type", "statements"],
"additionalProperties": false,
"properties": {
"name": { "type": "string" },
"async": { "type": "boolean" },
"params": {
"type": "array",
"items": { "$ref": "#/$defs/MethodParam" }
},
"return_type": {
"type": ["string", "null"],
"description": "TypeScript return type annotation, if present."
},
"statements": {
"type": "integer",
"description": "Statement count in method body."
}
}
},
"MethodParam": {
"type": "object",
"required": ["name"],
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "Parameter name."
},
"type": {
"type": ["string", "null"],
"description": "TypeScript type annotation, if present."
}
}
},
"InterfaceSignature": {
"type": "object",
"description": "Typed API method signature from abstract interface declaration. Has name, params, and return type but no method body (unlike MethodAST).",
"required": ["name", "params", "return_type"],
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "Method name (e.g., 'publicGetTicker', 'privatePostOrder')."
},
"params": {
"type": "array",
"items": { "$ref": "#/$defs/MethodParam" },
"description": "Parameter list with names and TypeScript type annotations."
},
"return_type": {
"type": ["string", "null"],
"description": "TypeScript return type annotation (typically 'Promise<implicitReturnType>')."
}
}
},
"MethodAST": {
"type": "object",
"description": "Complete method with full ESTree AST body. Used for sign(), handleErrors(), parse*(), watch*(), handle*(), and override methods.",
"required": ["async", "params", "return_type", "statements", "body"],
"additionalProperties": false,
"properties": {
"async": { "type": "boolean" },
"params": {
"type": "array",
"items": { "$ref": "#/$defs/MethodParam" }
},
"return_type": {
"type": ["string", "null"]
},
"statements": {
"type": "integer"
},
"body": {
"$ref": "#/$defs/ASTNode",
"description": "Complete ESTree BlockStatement AST. Preserves all node types, position info (start/end byte offsets), and nested structure."
}
}
},
"ASTNode": {
"type": "object",
"description": "ESTree AST node. Shape varies by node type. Always has 'type' field. Position info via 'start'/'end' byte offsets. Permissive schema — ESTree nodes are too varied to enumerate exhaustively.",
"required": ["type"],
"additionalProperties": true,
"properties": {
"type": {
"type": "string",
"description": "ESTree node type (e.g., 'BlockStatement', 'VariableDeclaration', 'CallExpression')."
},
"start": {
"type": "integer",
"description": "Start byte offset in source file."
},
"end": {
"type": "integer",
"description": "End byte offset in source file."
}
}
},
"HandleErrorsData": {
"type": "object",
"description": "handleErrors() method AST plus exception mappings from describe().",
"required": ["method", "exceptions", "http_exceptions", "error_code_fields", "throw_dispatches"],
"additionalProperties": false,
"properties": {
"method": {
"$ref": "#/$defs/MethodAST",
"description": "The handleErrors() method AST."
},
"exceptions": {
"oneOf": [
{ "type": "null" },
{
"type": "object",
"additionalProperties": true,
"description": "Exception mappings from describe().exceptions. Keys include 'broad' and 'exact' plus market-type-specific keys (e.g., 'spot', 'inverse', 'linear', 'option'). Values are objects mapping error strings to error class names."
}
],
"description": "Exception mappings from describe().exceptions. Null if not available."
},
"http_exceptions": {
"oneOf": [
{ "type": "null" },
{
"type": "object",
"additionalProperties": { "type": "string" },
"description": "HTTP status code -> error class name mapping."
}
],
"description": "HTTP exception mappings from describe().httpExceptions. Null if not available."
},
"error_code_fields": {
"type": "array",
"description": "Derived from handleErrors() AST: all this.safeString/safeString2/safeValue calls that extract error codes and messages from API responses. Each entry records the object, field name, safe* method used, and alternate field (for safeString2).",
"items": {
"$ref": "#/$defs/ErrorCodeFieldEntry"
}
},
"throw_dispatches": {
"type": "array",
"description": "Derived from handleErrors() AST: one entry per this.throwExactlyMatchedException / throwBroadlyMatchedException call. Each entry records which helper was called, the normalized exceptions-map source (exceptions/exceptions.exact/exceptions.broad/by_url.exact/by_url.broad/other), a raw string rendering of the source expression (anti-rot hatch), the resolved safe* binding for the lookup variable (arg[1]), and the unique resolved safe* binding referenced anywhere in the message expression (arg[2]) when one can be proven.",
"items": {
"$ref": "#/$defs/ThrowDispatchEntry"
}
}
}
},
"ThrowDispatchEntry": {
"type": "object",
"description": "A single this.throw{Exactly,Broadly}MatchedException dispatch in handleErrors(). Pairs the exceptions-map source with the safe* binding that feeds the lookup argument, and with the unique safe* binding referenced by the message expression when derivable, so consumers can reconstruct code/message pairings without re-parsing the AST.",
"required": ["helper", "exceptions_source", "exceptions_source_raw", "lookup", "message_lookup"],
"additionalProperties": false,
"properties": {
"helper": {
"type": "string",
"enum": ["throwExactlyMatchedException", "throwBroadlyMatchedException"]
},
"exceptions_source": {
"type": "string",
"enum": ["exceptions", "exceptions.exact", "exceptions.broad", "by_url.exact", "by_url.broad", "other"],
"description": "Normalized tag for arg[0]. 'exceptions' covers bare this.exceptions. 'exceptions.exact'/'exceptions.broad' cover both this.exceptions['exact'] and this.exceptions.exact shapes. 'by_url.*' covers this.getExceptionsByUrl(url, 'exact'|'broad'). 'other' is the anti-rot fallback — use exceptions_source_raw to disambiguate."
},
"exceptions_source_raw": {
"type": "string",
"description": "Compact string rendering of the arg[0] AST (always present). Anti-rot hatch so consumers can still inspect the original expression when exceptions_source is 'other'."
},
"lookup": {
"oneOf": [
{ "type": "null" },
{
"type": "object",
"required": ["object", "object_path", "field", "field2", "method"],
"additionalProperties": false,
"properties": {
"object": { "oneOf": [{ "type": "null" }, { "type": "string" }] },
"object_path": {
"oneOf": [
{ "type": "null" },
{ "type": "array", "items": { "type": "string" } }
]
},
"field": { "oneOf": [{ "type": "null" }, { "type": "string" }, { "type": "integer" }] },
"field2": { "oneOf": [{ "type": "null" }, { "type": "string" }, { "type": "integer" }] },
"method": {
"oneOf": [
{ "type": "null" },
{ "type": "string", "enum": ["safeString", "safeString2", "safeValue"] }
]
}
}
}
],
"description": "Resolved safe* binding for arg[1], or null when arg[1] is not a bound Identifier. Shape mirrors ErrorCodeFieldEntry minus roles/sentinel_values, plus method to save a cross-reference."
},
"message_lookup": {
"oneOf": [
{ "type": "null" },
{
"type": "object",
"required": ["object", "object_path", "field", "field2", "method"],
"additionalProperties": false,
"properties": {
"object": { "oneOf": [{ "type": "null" }, { "type": "string" }] },
"object_path": {
"oneOf": [
{ "type": "null" },
{ "type": "array", "items": { "type": "string" } }
]
},
"field": { "oneOf": [{ "type": "null" }, { "type": "string" }, { "type": "integer" }] },
"field2": { "oneOf": [{ "type": "null" }, { "type": "string" }, { "type": "integer" }] },
"method": {
"oneOf": [
{ "type": "null" },
{ "type": "string", "enum": ["safeString", "safeString2", "safeValue"] }
]
}
}
}
],
"description": "Resolved safe* binding for the unique lookup value referenced anywhere in arg[2], or null when the message expression does not point at a single bound lookup value."
}
}
},
"ErrorCodeFieldEntry": {
"type": "object",
"description": "A single this.safe*(object, field) call found in handleErrors() AST, with role classification based on how the extracted value is used. Roles are derived structurally from the AST: throwExactlyMatchedException usage → error_code (value used as exact-map lookup key, typically a short identifier like Bybit's retCode or OKX's sCode — not necessarily numeric). throwBroadlyMatchedException usage → error_message (value is the message string scanned for substring matches in the broad-map). === / !== comparisons → status_sentinel with operator preserved for polarity detection. A field that flows through both throw helpers in the same handleErrors() accumulates both roles.",
"required": ["object", "object_path", "field", "method", "field2", "roles", "sentinel_values"],
"additionalProperties": false,
"properties": {
"object": {
"oneOf": [{ "type": "null" }, { "type": "string" }],
"description": "The identifier name of the first argument (e.g., 'response', 'error', 'data'). Null if the first argument is not an Identifier node."
},
"object_path": {
"oneOf": [
{ "type": "null" },
{ "type": "array", "items": { "type": "string" } }
],
"description": "Derivation path tracing the object back to the response parameter. E.g., ['response', 'data', 'failure', '0'] means the object was derived via response['data']['failure'][0]. Null when the object is 'response' directly (trivial path) or when the derivation chain cannot be resolved."
},
"field": {
"oneOf": [{ "type": "null" }, { "type": "string" }, { "type": "integer" }],
"description": "The literal value of the second argument — the field name being accessed (e.g., 'code', 'msg'). Integer for array index access. Null if not a Literal node."
},
"method": {
"type": "string",
"enum": ["safeString", "safeString2", "safeValue"],
"description": "Which safe* method was called."
},
"field2": {
"oneOf": [{ "type": "null" }, { "type": "string" }, { "type": "integer" }],
"description": "For safeString2: the alternate field name (third argument). Null for safeString/safeValue or when not provided."
},
"roles": {
"type": "array",
"items": {
"type": "string",
"enum": ["error_code", "error_message", "status_sentinel"]
},
"description": "How this field's value is used in handleErrors(). error_code: passed to throwExactlyMatchedException as the exact-map lookup key (dispatches to an exception class via `exceptions.exact[value]`). error_message: passed to throwBroadlyMatchedException as the string to scan for substrings of `exceptions.broad` keys. status_sentinel: compared against literal values via === or !== (see sentinel_values for captured literals and polarity). A field can have multiple roles when its value flows through more than one of these helpers. Empty array when the variable's usage is not structurally resolvable."
},
"sentinel_values": {
"oneOf": [
{ "type": "null" },
{
"type": "array",
"items": {
"type": "object",
"required": ["value", "operator"],
"additionalProperties": false,
"properties": {
"value": { "type": "string", "description": "The literal value being compared against, stringified." },
"operator": { "type": "string", "enum": ["===", "!=="], "description": "The comparison operator used. Consumers can determine polarity: === with early-return means success value, !== with throw means success value (negated), === with throw means error value." }
}
}
}
],
"description": "Literal values compared against this field via === or !== operators, sorted by value. Each entry includes the operator for polarity detection. Null when the field has no status_sentinel role."
}
}
},
"PaginationEntry": {
"type": "object",
"description": "Pagination strategy and parameters for a single call site. Each entry includes provenance (containing_method, target_method). Strategy-specific fields (cursor_received, cursor_sent, cursor_increment, page_key) are present only for relevant strategies.",
"required": ["strategy", "containing_method", "target_method"],
"additionalProperties": true,
"properties": {
"strategy": {
"type": "string",
"enum": ["dynamic", "deterministic", "cursor", "incremental"],
"description": "Pagination strategy type."
},
"containing_method": {
"type": "string",
"description": "Name of the method body where this pagination call was found (e.g. 'fetchAccountsV2')."
},
"target_method": {
"type": ["string", "null"],
"description": "Target method name passed to fetchPaginatedCall* (first argument). Null when the argument is a runtime variable rather than a string literal."
},
"max_entries_per_request": {
"type": ["integer", "null"],
"description": "Maximum entries per paginated API call. Null when not statically resolvable from source."
},
"cursor_received": {
"type": ["string", "null"],
"description": "Field name in response to extract next cursor (cursor strategy only)."
},
"cursor_sent": {
"type": ["string", "null"],
"description": "Field name to send cursor in request (cursor strategy only)."
},
"cursor_increment": {
"type": ["integer", "null"],
"description": "Numeric increment for cursor values (cursor strategy only)."
},
"page_key": {
"type": ["string", "null"],
"description": "Parameter name for page number (incremental strategy only)."
}
}
},
"OverridesData": {
"type": "object",
"description": "Method override analysis for exchanges that extend another exchange. Grouped by REST/WS class.",
"required": ["extends", "rest", "ws"],
"additionalProperties": false,
"properties": {
"extends": {
"type": "string",
"description": "Parent exchange id (e.g., 'binance' for binanceus)."
},
"rest": {
"oneOf": [
{ "type": "null" },
{ "$ref": "#/$defs/OverrideEntry" }
],
"description": "REST class override details. Null if no REST-specific override."
},
"ws": {
"oneOf": [
{ "type": "null" },
{ "$ref": "#/$defs/OverrideEntry" }
],
"description": "WS class override details. Null if no WS-specific override."
}
}
},
"OverrideEntry": {
"type": "object",
"description": "Override details for a single class (REST or WS).",
"required": ["parent_key", "overridden", "new_methods", "inherited"],
"additionalProperties": false,
"properties": {
"parent_key": {
"type": "string",
"description": "Parent node_key (e.g., 'rest:binance')."
},
"overridden": {
"type": "object",
"additionalProperties": { "$ref": "#/$defs/MethodAST" },
"description": "Map of overridden method name -> MethodAST. These methods exist on the parent and are redefined."
},
"new_methods": {
"type": "object",
"additionalProperties": { "$ref": "#/$defs/MethodAST" },
"description": "Map of new method name -> MethodAST. These methods don't exist on the parent."
},
"inherited": {
"type": "array",
"items": { "type": "string" },
"description": "List of method names inherited from the parent (names only, no AST)."
}
}
}
}
}