{ "openapi": "3.1.0", "info": { "title": "Edified Lab x402 API (api.edifiedlab.com)", "version": "0.1.0", "description": "Paid HTTP API using the x402 payment protocol (HTTP 402 + USDC). Paid operations include OpenAPI diff, page extraction, Black-Scholes option pricing, FX conversion, clinical-trials search, SEC EDGAR, P&L stats, identifier validation, structured-data tools, and index constituents. Unauthenticated calls receive HTTP 402 with paymentRequirements; clients pay and retry with the payment proof. There is no standardized OpenAPI vendor extension for x402 \u2014 payment is communicated by the real 402 response. Rate limiting applies to every path, including free discovery and error probes: the free-surface bucket allows 30 requests per 60-second sliding window per client IP, while paid-capable routes use a separate 120 requests per 60-second bucket. A throttled request returns HTTP 429 with {\"error\":\"rate_limited\"} and Retry-After set to the seconds remaining in the window (typically 60); wait before retrying." }, "servers": [ { "url": "https://api.edifiedlab.com" } ], "paths": { "/v1/tools/openapi/compare": { "post": { "operationId": "compareOpenapiSpecs", "summary": "Diff two OpenAPI specs: breaking changes, added paths, and contract drift.", "description": "Diff two OpenAPI specs: breaking changes, added paths, and contract drift.", "parameters": [ { "name": "X-AFE-Credit", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Credit token from POST /v1/agent/credits/purchase." }, { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v1 payment proof (`challenge_id:proof`). Primary request header. Legacy alias `X-AFE-Payment` is also accepted (same value, case-insensitive); sending both with disagreeing values returns 400." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v2 payment proof. Primary request header for stock v2 clients." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "base_spec": { "oneOf": [ { "type": "string" }, { "type": "object" }, { "type": "array" } ], "example": "{\"openapi\": \"3.0.0\", \"info\": {\"title\": \"Widget API\", \"version\": \"1.1.0\"}, \"paths\": {\"/widgets\": {\"get\": {\"summary\": \"List widgets\", \"responses\": {\"200\": {\"description\": \"OK\"}}}}, \"/widgets/{id}\": {\"get\": {\"summary\": \"Get a widget\", \"responses\": {\"200\": {\"description\": \"OK\"}}}}}}" }, "revised_spec": { "oneOf": [ { "type": "string" }, { "type": "object" }, { "type": "array" } ], "example": "{\"openapi\": \"3.0.0\", \"info\": {\"title\": \"Widget API\", \"version\": \"1.1.0\"}, \"paths\": {\"/widgets\": {\"get\": {\"summary\": \"List widgets\", \"responses\": {\"200\": {\"description\": \"OK\"}}}}, \"/widgets/{id}\": {\"get\": {\"summary\": \"Get a widget\", \"responses\": {\"200\": {\"description\": \"OK\"}}}}}}" }, "base_openapi": { "oneOf": [ { "type": "string" }, { "type": "object" }, { "type": "array" } ], "example": "{\"openapi\": \"3.0.0\", \"info\": {\"title\": \"Widget API\", \"version\": \"1.1.0\"}, \"paths\": {\"/widgets\": {\"get\": {\"summary\": \"List widgets\", \"responses\": {\"200\": {\"description\": \"OK\"}}}}, \"/widgets/{id}\": {\"get\": {\"summary\": \"Get a widget\", \"responses\": {\"200\": {\"description\": \"OK\"}}}}}}" }, "revised_openapi": { "oneOf": [ { "type": "string" }, { "type": "object" }, { "type": "array" } ], "example": "{\"openapi\": \"3.0.0\", \"info\": {\"title\": \"Widget API\", \"version\": \"1.1.0\"}, \"paths\": {\"/widgets\": {\"get\": {\"summary\": \"List widgets\", \"responses\": {\"200\": {\"description\": \"OK\"}}}}, \"/widgets/{id}\": {\"get\": {\"summary\": \"Get a widget\", \"responses\": {\"200\": {\"description\": \"OK\"}}}}}}" }, "path_count": { "type": "integer", "maximum": 5000, "example": 10 } }, "allOf": [ { "anyOf": [ { "required": [ "base_spec" ] }, { "required": [ "base_openapi" ] } ] }, { "anyOf": [ { "required": [ "revised_spec" ] }, { "required": [ "revised_openapi" ] } ] } ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OpenAPI compatibility report" }, "400": { "description": "Invalid OpenAPI specifications" }, "402": { "description": "Payment required \u2014 see paymentRequirements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequiredBody" } } }, "headers": { "PAYMENT-REQUIRED": { "description": "x402 v2 Payment-Required header (base64-encoded paymentRequirements). The stack emits this as PAYMENT-REQUIRED.", "schema": { "type": "string" } }, "X-Afe-Payment-Required": { "description": "Set to `1` when this response is a payment challenge.", "schema": { "type": "string", "enum": [ "1" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "X-PAYMENT": [] }, { "PAYMENT-SIGNATURE": [] } ] } }, "/health": { "get": { "operationId": "health", "summary": "Liveness", "responses": { "200": { "description": "ok" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/openapi.json": { "get": { "operationId": "openapi", "summary": "This OpenAPI document", "responses": { "200": { "description": "OpenAPI 3 JSON" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/docs": { "get": { "operationId": "swaggerUi", "summary": "Swagger UI for this API", "responses": { "200": { "description": "HTML" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/market/black-scholes": { "post": { "operationId": "blackScholesCalculate", "summary": "Black-Scholes option price and Greeks (delta, gamma, vega, theta) from JSON keys spot, strike, tau (years; 3-month = 0.25), sigma (annualized volatility), and is_call (boolean). Pure closed-form calculation, no market data looked up or stored. vega is \u2202price/\u2202sigma per 1.0 volatility (not per 1%).", "description": "Black-Scholes option price and Greeks (delta, gamma, vega, theta) from JSON keys spot, strike, tau (years; 3-month = 0.25), sigma (annualized volatility), and is_call (boolean). Pure closed-form calculation, no market data looked up or stored. vega is \u2202price/\u2202sigma per 1.0 volatility (not per 1%).", "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v1 payment proof (`challenge_id:proof`). Primary request header. Legacy alias `X-AFE-Payment` is also accepted (same value, case-insensitive); sending both with disagreeing values returns 400." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v2 payment proof. Primary request header for stock v2 clients." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "spot", "strike", "tau", "sigma", "is_call" ], "properties": { "spot": { "type": "number", "exclusiveMinimum": 0, "example": 100.0 }, "strike": { "type": "number", "exclusiveMinimum": 0, "example": 100.0 }, "tau": { "type": "number", "minimum": 0, "description": "time to expiry in years (3-month = 0.25)", "example": 0.25 }, "sigma": { "type": "number", "minimum": 0, "description": "annualized volatility", "example": 0.2 }, "is_call": { "type": "boolean", "description": "true for a call, false for a put", "example": true }, "rate": { "type": "number", "default": 0.0, "description": "annualized risk-free rate (optional; default 0)", "example": 0.0 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Calculated option price and Greeks" }, "400": { "description": "Invalid caller-supplied inputs" }, "402": { "description": "Payment required (includes extensions.bazaar)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequiredBody" } } }, "headers": { "PAYMENT-REQUIRED": { "description": "x402 v2 Payment-Required header (base64-encoded paymentRequirements). The stack emits this as PAYMENT-REQUIRED.", "schema": { "type": "string" } }, "X-Afe-Payment-Required": { "description": "Set to `1` when this response is a payment challenge.", "schema": { "type": "string", "enum": [ "1" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "X-PAYMENT": [] }, { "PAYMENT-SIGNATURE": [] } ] } }, "/v1/market/fx-convert": { "post": { "operationId": "fxConvert", "summary": "Currency conversion and FX rates from public daily/historical ECB reference data.", "description": "Convert an amount between currencies using public daily/historical FX rates backed by ECB reference data.", "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v1 payment proof (`challenge_id:proof`). Primary request header. Legacy alias `X-AFE-Payment` is also accepted (same value, case-insensitive); sending both with disagreeing values returns 400." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v2 payment proof. Primary request header for stock v2 clients." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "", "convert", "latest", "historical", "currencies" ], "description": "Empty string is treated as convert.", "example": "convert" }, "from": { "type": "string", "pattern": "^[A-Za-z]{3}$", "example": "USD" }, "to": { "oneOf": [ { "type": "string", "pattern": "^[A-Za-z]{3}(,[A-Za-z]{3})*$" }, { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "minItems": 1 } ], "example": "EUR,GBP,JPY", "description": "Comma-separated quotes or array of 3-letter codes for latest/historical" }, "base": { "type": "string", "pattern": "^[A-Za-z]{3}$", "example": "USD", "description": "Live alias for `from` on latest/historical (Frankfurter base)." }, "symbols": { "oneOf": [ { "type": "string", "pattern": "^[A-Za-z]{3}(,[A-Za-z]{3})*$" }, { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "minItems": 1 } ], "example": "EUR,GBP,JPY", "description": "Comma-separated quotes or array of 3-letter codes for latest/historical" }, "amount": { "type": "number", "exclusiveMinimum": 0, "example": 100.0 }, "date": { "type": "string", "format": "date", "example": "2026-09-03", "description": "YYYY-MM-DD for historical action" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Converted amount / rates" }, "400": { "description": "Invalid caller-supplied inputs" }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequiredBody" } } }, "headers": { "PAYMENT-REQUIRED": { "description": "x402 v2 Payment-Required header (base64-encoded paymentRequirements). The stack emits this as PAYMENT-REQUIRED.", "schema": { "type": "string" } }, "X-Afe-Payment-Required": { "description": "Set to `1` when this response is a payment challenge.", "schema": { "type": "string", "enum": [ "1" ] } } } }, "503": { "description": "Upstream FX rate service unavailable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "X-PAYMENT": [] }, { "PAYMENT-SIGNATURE": [] } ] } }, "/v1/tools/extract-text": { "post": { "operationId": "extractCleanText", "summary": "Extract clean readable text from caller-supplied HTML (no URL fetch).", "description": "Extract clean readable text from caller-supplied HTML (no URL fetch).", "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v1 payment proof (`challenge_id:proof`). Primary request header. Legacy alias `X-AFE-Payment` is also accepted (same value, case-insensitive); sending both with disagreeing values returns 400." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v2 payment proof. Primary request header for stock v2 clients." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "html": { "type": "string", "minLength": 24, "description": "Decoded HTML, minimum 24 characters. Tiny fragments such as

hello

are rejected unpaid (400) before a 402 challenge.", "example": "

Quarterly revenue grew 12% year-over-year.

" }, "html_b64": { "type": "string", "contentEncoding": "base64", "description": "Base64-encoded UTF-8 HTML; decoded text must be at least 24 characters (same floor as html minLength).", "example": "PGh0bWw+PGJvZHk+PHA+UXVhcnRlcmx5IHJldmVudWUgZ3JldyAxMiUgeWVhci1vdmVyLXllYXIuPC9wPjwvYm9keT48L2h0bWw+" }, "content_b64": { "type": "string", "contentEncoding": "base64", "description": "Alias of html_b64; decoded text must be at least 24 characters.", "example": "PGh0bWw+PGJvZHk+PHA+UXVhcnRlcmx5IHJldmVudWUgZ3JldyAxMiUgeWVhci1vdmVyLXllYXIuPC9wPjwvYm9keT48L2h0bWw+" } }, "anyOf": [ { "required": [ "html" ] }, { "required": [ "html_b64" ] }, { "required": [ "content_b64" ] } ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Clean extracted text" }, "400": { "description": "Invalid HTML input" }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequiredBody" } } }, "headers": { "PAYMENT-REQUIRED": { "description": "x402 v2 Payment-Required header (base64-encoded paymentRequirements). The stack emits this as PAYMENT-REQUIRED.", "schema": { "type": "string" } }, "X-Afe-Payment-Required": { "description": "Set to `1` when this response is a payment challenge.", "schema": { "type": "string", "enum": [ "1" ] } } } }, "503": { "description": "Extraction service unavailable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "X-PAYMENT": [] }, { "PAYMENT-SIGNATURE": [] } ] } }, "/v1/tools/validate": { "post": { "operationId": "validateData", "summary": "Validate IBAN, ISBN, and similar identifiers by format and checksum (not real-world verification).", "description": "Validate IBAN, ISBN, and similar identifiers by format and checksum (not real-world verification).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "enum": [ "jsonschema", "identifier", "phone" ], "example": "identifier" }, "schema": { "type": "object", "example": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "document": { "example": { "name": "example" } }, "scheme": { "type": "string", "enum": [ "bic", "ean", "ean8", "ean13", "ean14", "gs1_128", "iban", "imei", "imsi", "isbn", "isbn10", "isbn13", "isin", "ismn", "isni", "issn", "lei", "mac", "meid", "vatin" ], "example": "isbn13" }, "value": { "type": "string", "example": "9780306406157" }, "region": { "type": "string", "example": "US" } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "type": { "const": "identifier" } }, "required": [ "type" ] }, "then": { "required": [ "scheme", "value" ] } }, { "if": { "properties": { "type": { "const": "jsonschema" } }, "required": [ "type" ] }, "then": { "required": [ "schema", "document" ] } }, { "if": { "properties": { "type": { "const": "phone" } }, "required": [ "type" ] }, "then": { "required": [ "value" ] } } ] } } } }, "responses": { "200": { "description": "Validation result (format/checksum only; no real-world verification)" }, "400": { "description": "Invalid input" }, "402": { "description": "Payment required (includes extensions.bazaar)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequiredBody" } } }, "headers": { "PAYMENT-REQUIRED": { "description": "x402 v2 Payment-Required header (base64-encoded paymentRequirements). The stack emits this as PAYMENT-REQUIRED.", "schema": { "type": "string" } }, "X-Afe-Payment-Required": { "description": "Set to `1` when this response is a payment challenge.", "schema": { "type": "string", "enum": [ "1" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "X-PAYMENT": [] }, { "PAYMENT-SIGNATURE": [] } ], "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v1 payment proof (`challenge_id:proof`). Primary request header. Legacy alias `X-AFE-Payment` is also accepted (same value, case-insensitive); sending both with disagreeing values returns 400." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v2 payment proof. Primary request header for stock v2 clients." } ] } }, "/v1/tools/structured-data": { "post": { "operationId": "processStructuredData", "summary": "Diff/patch JSON, and validate XML/XSD or CSV/tabular data (not OpenAPI-specific).", "description": "Diff/patch JSON, and validate XML/XSD or CSV/tabular data (not OpenAPI-specific).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "op" ], "properties": { "op": { "type": "string", "enum": [ "json_diff", "json_patch", "xml_validate", "csv_validate" ], "example": "json_diff" }, "base": { "example": { "name": "widget", "price": 9.99 } }, "revised": { "example": { "name": "widget", "price": 12.99 } }, "document": { "example": { "name": "widget", "price": 9.99 } }, "patch": { "type": "array", "example": [ { "op": "replace", "path": "/price", "value": 12.99 } ] }, "xml": { "type": "string", "example": "1" }, "xsd": { "type": "string", "example": "" }, "csv": { "type": "string", "example": "name,price\nwidget,9.99" }, "schema": { "type": "object", "example": { "type": "object" } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Structured-data operation result" }, "400": { "description": "Invalid input" }, "402": { "description": "Payment required (includes extensions.bazaar)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequiredBody" } } }, "headers": { "PAYMENT-REQUIRED": { "description": "x402 v2 Payment-Required header (base64-encoded paymentRequirements). The stack emits this as PAYMENT-REQUIRED.", "schema": { "type": "string" } }, "X-Afe-Payment-Required": { "description": "Set to `1` when this response is a payment challenge.", "schema": { "type": "string", "enum": [ "1" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "X-PAYMENT": [] }, { "PAYMENT-SIGNATURE": [] } ], "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v1 payment proof (`challenge_id:proof`). Primary request header. Legacy alias `X-AFE-Payment` is also accepted (same value, case-insensitive); sending both with disagreeing values returns 400." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v2 payment proof. Primary request header for stock v2 clients." } ] } }, "/v1/market/indices": { "get": { "operationId": "lookupIndexConstituents", "summary": "S&P 500, Nasdaq-100, and Russell 2000 constituents and GICS sectors.", "description": "Returns index constituents and GICS-style sectors. Accepted query parameters are only `index` (required at grant time; case-insensitive; aliases ndx/nasdaq, rut/russell, sp/s&p500; SPX is not an index and stays 400) and optional `ticker`. Other query names are not part of the request contract; OpenAPI lists the full accepted set before a 402. A live response has `degraded` false and `source` `live`. Members below the serving floor (`degraded`/`fallback_sample`) are omitted from the served enum and refuse HTTP 400 payload_not_ready before a 402 (does not charge). Discovery probes still 402 while at least one member is live.", "parameters": [ { "name": "index", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "S&P500", "SP", "SP500", "s&p500", "sp", "sp500" ], "example": "sp500", "description": "Case-insensitive. Aliases ndx/nasdaq\u2192nasdaq100, rut/russell\u2192russell2000, sp/s&p500\u2192sp500. SPX is not an index and stays 400." } }, { "name": "ticker", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "example": "AAPL" } }, { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v1 payment proof (`challenge_id:proof`). Primary request header. Legacy alias `X-AFE-Payment` is also accepted (same value, case-insensitive); sending both with disagreeing values returns 400." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v2 payment proof. Primary request header for stock v2 clients." } ], "responses": { "200": { "description": "Index constituents (with sectors where available)" }, "400": { "description": "Invalid or unsupported index" }, "402": { "description": "Payment required (includes extensions.bazaar)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequiredBody" } } }, "headers": { "PAYMENT-REQUIRED": { "description": "x402 v2 Payment-Required header (base64-encoded paymentRequirements). The stack emits this as PAYMENT-REQUIRED.", "schema": { "type": "string" } }, "X-Afe-Payment-Required": { "description": "Set to `1` when this response is a payment challenge.", "schema": { "type": "string", "enum": [ "1" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "X-PAYMENT": [] }, { "PAYMENT-SIGNATURE": [] } ] } }, "/v1/market/clinical-trials": { "get": { "operationId": "clinicalTrialsSearch", "summary": "Search ClinicalTrials.gov with query= (company, drug, or intervention name).", "description": "Search ClinicalTrials.gov with query= (company, drug, or intervention name).", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "example": "Nivolumab" } }, { "name": "max_results", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10, "example": 10 } }, { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v1 payment proof (`challenge_id:proof`). Primary request header. Legacy alias `X-AFE-Payment` is also accepted (same value, case-insensitive); sending both with disagreeing values returns 400." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v2 payment proof. Primary request header for stock v2 clients." } ], "responses": { "200": { "description": "Formatted ClinicalTrials.gov registry results" }, "400": { "description": "Invalid query or result limit" }, "402": { "description": "Payment required (includes extensions.bazaar)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequiredBody" } } }, "headers": { "PAYMENT-REQUIRED": { "description": "x402 v2 Payment-Required header (base64-encoded paymentRequirements). The stack emits this as PAYMENT-REQUIRED.", "schema": { "type": "string" } }, "X-Afe-Payment-Required": { "description": "Set to `1` when this response is a payment challenge.", "schema": { "type": "string", "enum": [ "1" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "X-PAYMENT": [] }, { "PAYMENT-SIGNATURE": [] } ] } }, "/v1/market/pnl-stats": { "post": { "operationId": "pnlStatsCalculate", "summary": "Trade P&L stats from caller returns: win rate, profit factor, drawdown.", "description": "Compute trade P&L statistics from caller-supplied realized P&L values: win rate, profit factor, max drawdown, and rolling-window statistics. No market data or account access -- purely a function of the numbers supplied.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pnls" ], "properties": { "pnls": { "type": "array", "minItems": 1, "maxItems": 5000, "items": { "type": "number" }, "example": [ 120.5, -45.0, 300.25, -10.0, 88.0 ] }, "rolling_window": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 20, "example": 20 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Calculated trade P&L statistics" }, "402": { "description": "Payment required (includes extensions.bazaar)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequiredBody" } } }, "headers": { "PAYMENT-REQUIRED": { "description": "x402 v2 Payment-Required header (base64-encoded paymentRequirements). The stack emits this as PAYMENT-REQUIRED.", "schema": { "type": "string" } }, "X-Afe-Payment-Required": { "description": "Set to `1` when this response is a payment challenge.", "schema": { "type": "string", "enum": [ "1" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "X-PAYMENT": [] }, { "PAYMENT-SIGNATURE": [] } ], "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v1 payment proof (`challenge_id:proof`). Primary request header. Legacy alias `X-AFE-Payment` is also accepted (same value, case-insensitive); sending both with disagreeing values returns 400." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v2 payment proof. Primary request header for stock v2 clients." } ] } }, "/v1/market/sec-edgar": { "post": { "operationId": "secEdgarLookup", "summary": "SEC EDGAR filings, Form 4 insider trades, and MD&A extract by ticker or CIK.", "description": "SEC EDGAR filings, Form 4 insider trades, and MD&A extract by ticker or CIK.", "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v1 payment proof (`challenge_id:proof`). Primary request header. Legacy alias `X-AFE-Payment` is also accepted (same value, case-insensitive); sending both with disagreeing values returns 400." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v2 payment proof. Primary request header for stock v2 clients." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "filings", "insider", "cik", "read" ], "default": "filings", "example": "filings" }, "ticker": { "type": "string", "description": "Equity ticker (required for filings/insider/cik)", "example": "AAPL" }, "form_type": { "type": "string", "default": "10-K", "description": "SEC form id for filings action", "example": "10-K" }, "max_results": { "type": "integer", "minimum": 1, "maximum": 50, "example": 5 }, "start_date": { "type": "string", "format": "date", "example": "2025-01-01" }, "end_date": { "type": "string", "format": "date", "example": "2026-09-03" }, "url": { "type": "string", "description": "EDGAR Archives URL for read action", "example": "https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/aapl-20240928.htm" }, "section_hint": { "type": "string", "enum": [ "mda", "risk_factors", "liquidity", "all" ], "default": "mda", "example": "mda" }, "max_chars": { "type": "integer", "minimum": 200, "maximum": 50000, "example": 20000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "EDGAR lookup result" }, "400": { "description": "Invalid caller-supplied inputs" }, "402": { "description": "Payment required (includes extensions.bazaar)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequiredBody" } } }, "headers": { "PAYMENT-REQUIRED": { "description": "x402 v2 Payment-Required header (base64-encoded paymentRequirements). The stack emits this as PAYMENT-REQUIRED.", "schema": { "type": "string" } }, "X-Afe-Payment-Required": { "description": "Set to `1` when this response is a payment challenge.", "schema": { "type": "string", "enum": [ "1" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "X-PAYMENT": [] }, { "PAYMENT-SIGNATURE": [] } ] } } }, "components": { "schemas": { "X402PaymentRequirements": { "type": "object", "description": "x402 payment requirements, same field names the CDP facilitator emits.", "properties": { "scheme": { "type": "string", "example": "exact" }, "network": { "type": "string", "description": "Settlement chain for this challenge." }, "maxAmountRequired": { "type": "string", "description": "Amount owed in the asset's atomic units, as a decimal string." }, "resource": { "type": "string", "description": "Route this challenge pays for." }, "description": { "type": "string" }, "mimeType": { "type": "string", "example": "application/json" }, "payTo": { "type": "string", "description": "Recipient address. Mock 402s use the zero address (no on-chain settle). Prod CDP uses a real treasury (0x5037\u2026). Spend-controls refusing zero payTo is expected client behavior, not a server bug." }, "maxTimeoutSeconds": { "type": "integer", "description": "Challenge lifetime; equals the top-level expires_at window." }, "asset": { "type": "string", "description": "Token contract address. Mock 402s use the zero address. Prod CDP uses Base USDC." }, "extra": { "type": "object", "description": "Payment-construction parameters. Mock 402s include challengeId, assetTransferMethod=permit2, and spenderAddress=the CREATE2 ExactPermit2Proxy (same address on every EVM chain, including Base) by design so a stock Permit2 builder can emit PAYMENT-SIGNATURE. Mock payTo and asset are the zero address; mock:true plus network=base-sepolia (v2 eip155:84532) mean no on-chain settle. Do not copy extra onto a funded mainnet wallet. Spend-controls refusing zero payTo is expected client behavior, not a server bug. Mock extra is a subset: it omits the EIP-712 name, version, and chainId keys that CDP /verify requires. Prod CDP extra is the full set (same CREATE2 spender plus name=USDC, version=2, chainId=8453, real non-zero payTo and Base USDC). Against the live CDP facilitator, omitting assetTransferMethod, spenderAddress, name or version makes /verify reject the payment. Do not omit or zero mock spenderAddress (that reopens PO-20260908-05).", "properties": { "challengeId": { "type": "string", "description": "The same value as the top-level challenge_id; echo it back in the payment's extra so the payment is bound to THIS challenge." }, "assetTransferMethod": { "type": "string", "example": "permit2", "description": "Mechanism router for the official x402 client. When absent a standard client defaults to raw EIP-3009, which CDP's live /verify rejects; \"permit2\" selects the Permit2 payload CDP requires. Present on mock and prod." }, "spenderAddress": { "type": "string", "description": "ExactPermit2Proxy the payer must name as Permit2 spender. CREATE2 vanity 0x402085c2\u20260001, same address on every EVM chain including Base. Mock 402s emit this protocol address next to zero payTo/asset by design \u2014 it is not a leaked mainnet custody address. Stock PAYMENT-SIGNATURE clients read this from extra; omitting it lets them sign a different spender and the payment is rejected as invalid_payment. Do not omit or zero it on mock." }, "name": { "type": "string", "description": "Asset EIP-712 domain name (CDP-only; mock extra omits this). CDP rebuilds the payment's EIP-712 domain from this; without it /verify rejects with missing EIP-712 domain parameters. Prod emits USDC." }, "version": { "type": "string", "description": "Asset EIP-712 domain version (CDP-only; mock extra omits this). Required alongside name for the same reason. Prod emits 2." }, "chainId": { "type": "integer", "description": "EVM chain id for the advertised network (CDP-only; mock extra omits this). Prod CDP emits 8453 (Base). When echoed it MUST match, or the payment is rejected." } } }, "extensions": { "type": "object", "description": "x402 extensions (docs.x402.org/extensions/bazaar); mirrored at the top level." }, "serviceName": { "type": "string", "description": "Human-readable service label advertised to Bazaar." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Discovery tags advertised to Bazaar." } } }, "X402PaymentRequiredBody": { "type": "object", "description": "Body returned with HTTP 402. Everything needed to pay and retry is in this response: take `challenge_id`, settle `paymentRequirements`, then repeat the original request with `X-PAYMENT: :` (v1) or `PAYMENT-SIGNATURE` (v2). Legacy `X-AFE-Payment` is an alias of `X-PAYMENT`, same value.", "required": [ "error", "challenge_id", "payment_required", "paymentRequirements" ], "properties": { "error": { "type": "string", "example": "payment_required" }, "challenge_id": { "type": "string", "description": "Identifier to quote in X-PAYMENT (or its X-AFE-Payment alias) / bind into PAYMENT-SIGNATURE extra. Obtained HERE \u2014 no separate challenge endpoint is called." }, "amount_usd": { "type": "number", "description": "Price in USD." }, "chain": { "type": "string" }, "resource": { "type": "string" }, "description": { "type": "string" }, "mock": { "type": "boolean", "description": "True when served by MockFacilitator: payTo and asset are zeros, network is base-sepolia, extra.spenderAddress is the CREATE2 ExactPermit2Proxy by design, and there is no on-chain settle. False on live CDP." }, "payment_required": { "type": "boolean", "example": true }, "expires_at": { "type": "number", "description": "Unix epoch seconds after which challenge_id is dead." }, "paymentRequirements": { "$ref": "#/components/schemas/X402PaymentRequirements" }, "extensions": { "type": "object", "description": "Copy of paymentRequirements.extensions, lifted so standard x402 clients need not descend." } } }, "X402RateLimitedBody": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "const": "rate_limited", "example": "rate_limited" } } } }, "securitySchemes": { "X-PAYMENT": { "type": "apiKey", "in": "header", "name": "X-PAYMENT", "description": "x402 v1 payment proof (`challenge_id:proof`). Primary request header. Legacy alias `X-AFE-Payment` is also accepted (same value, case-insensitive); sending both with disagreeing values returns 400." }, "PAYMENT-SIGNATURE": { "type": "apiKey", "in": "header", "name": "PAYMENT-SIGNATURE", "description": "x402 v2 payment proof. Primary request header for stock v2 clients." } }, "parameters": { "X-PAYMENT": { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v1 payment proof (`challenge_id:proof`). Primary request header. Legacy alias `X-AFE-Payment` is also accepted (same value, case-insensitive); sending both with disagreeing values returns 400." }, "PAYMENT-SIGNATURE": { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v2 payment proof. Primary request header for stock v2 clients." } }, "responses": { "RateLimited": { "description": "Too many requests for this client bucket. Wait before retrying; the server sends Retry-After with the seconds remaining in the 60-second sliding window (example 60).", "headers": { "Retry-After": { "description": "Seconds remaining in the 60-second sliding window.", "schema": { "type": "integer", "minimum": 1, "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402RateLimitedBody" } } } } } } }