{"openapi":"3.1.0","info":{"title":"AIDeep API v1","version":"1.0.0","summary":"Datos agroeconómicos: series de mercado, fundamentals, comercio, pronósticos y simulación de shocks.","description":"API de datos de AI Deep Economics para aplicaciones y agentes de IA.\n\nAtribución obligatoria: Fuentes: AgriShield (AIDeep), World Bank Pink Sheet (CC BY 4.0), FAO, IMF PCPS, FRED, INDEC/BCRA vía datos.gob.ar, MAGyP, Cámara Mercantil. Redistribución sujeta a las licencias de cada fuente.\n\nAutenticación: enviá tu clave en `X-Api-Key` o `Authorization: Bearer`. Los agentes sin\nclave pueden pagar por request con el protocolo x402 (HTTP 402); el estado vigente,\nla red y los precios se publican en `GET /api/v1`.","contact":{"name":"AI Deep Economics","url":"https://www.aideepeconomics.com/contact.html"},"termsOfService":"https://www.aideepeconomics.com/terms.html"},"servers":[{"url":"https://www.aideepeconomics.com","description":"Producción"}],"tags":[{"name":"series"},{"name":"nowcast"},{"name":"twin"},{"name":"fundamentals"},{"name":"trade"},{"name":"markets"},{"name":"esr"}],"paths":{"/api/v1/series":{"get":{"operationId":"listSeries","summary":"Series del observatorio con genealogía de fuentes.","tags":["series"],"x-scope":"series","security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"commodity","in":"query","required":false,"schema":{"type":"string"},"description":"opcional: carne|granos|lacteos|fertilizantes|energia|macro|otros"}]}},"/api/v1/series/{id}":{"get":{"operationId":"getSeriesById","summary":"Una serie por id.","tags":["series"],"x-scope":"series","security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador de ruta `id`."}]}},"/api/v1/nowcast":{"get":{"operationId":"getNowcast","summary":"Pronósticos 1-3 meses con backtest walk-forward (MAE vs naive, hit-rate, skill).","tags":["nowcast"],"x-scope":"nowcast","security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/twin/simulate":{"post":{"operationId":"simulateTwinShock","summary":"Propagación de shocks por el grafo causal (β, R² y confianza expuestos).","tags":["twin"],"x-scope":"twin","security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"shocks":[{"nodeId":"brent","pct":20}]}}}}}},"/api/v1/twin/graph":{"get":{"operationId":"getTwinGraph","summary":"Grafo causal con sensibilidades estimadas.","tags":["twin"],"x-scope":"twin","security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/fundamentals/{slug}":{"get":{"operationId":"getFundamentals","summary":"Oferta/demanda/stocks por país (USDA PSD + FAOSTAT): ranking, share, YoY, stock-to-use.","tags":["fundamentals"],"x-scope":"fundamentals","security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador de ruta `slug`."},{"name":"metric","in":"query","required":false,"schema":{"type":"string"},"description":"production|consumption|exports|imports|stocks"}]}},"/api/v1/trade/{slug}":{"get":{"operationId":"getTrade","summary":"Flujos bilaterales (UN Comtrade): rutas top con geo, concentración HHI y señales YoY.","tags":["trade"],"x-scope":"trade","security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador de ruta `slug`."},{"name":"flow","in":"query","required":false,"schema":{"type":"string"},"description":"exports|imports"}]}},"/api/v1/markets":{"get":{"operationId":"getMarketsBoard","summary":"Board de 13 futuros CBOT/ICE/CME (últ. cierre, Δ1d/30d/1a, vol 30d) + basis Cono Sur (pizarra UY vs CBOT, USD/ton).","tags":["markets"],"x-scope":"markets","security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/markets/series/{symbol}":{"get":{"operationId":"getMarketSeries","summary":"Serie diaria completa de un futuro (ej. ZS=F, ZC=F, LE=F).","tags":["markets"],"x-scope":"markets","security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador de ruta `symbol`."}]}},"/api/v1/esr/{slug}":{"get":{"operationId":"getEsr","summary":"Ventas semanales de exportación de EE.UU. (USDA ESR): headline, serie semanal y top compradores del año comercial.","tags":["esr"],"x-scope":"esr","security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador de ruta `slug`."}]}}},"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key"},"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"SuccessEnvelope":{"type":"object","description":"Envelope común. Los campos de datos varían por endpoint; `attribution` y `ok` están siempre.","properties":{"ok":{"type":"boolean","const":true},"attribution":{"type":"string","description":"Fuentes y licencias a citar al redistribuir."},"updatedAt":{"type":"string","description":"Última actualización de los datos servidos."}},"required":["ok"],"additionalProperties":true},"ErrorResponse":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"message":{"type":"string"}},"required":["ok","message"]}},"responses":{"Unauthorized":{"description":"Falta la API key o es inválida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"La key no tiene el scope requerido por el endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Se superó el límite horario del plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PaymentRequired":{"description":"Pago por request requerido (x402). El body trae `accepts` con red, receptor y precio; reintentá con el header `X-PAYMENT`.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"x-plans":[{"id":"free","label":"Free","scopes":["series","markets"],"rateLimitPerHour":300,"priceHint":"Gratis · atribución obligatoria","blurb":"Series del observatorio y board de futuros. Ideal para prototipos y uso académico."},{"id":"pro","label":"Pro","scopes":["series","markets","nowcast","fundamentals","trade","esr"],"rateLimitPerHour":2000,"priceHint":"USD 100/mes","blurb":"Todo Free + pronósticos con backtest, fundamentals USDA/FAOSTAT, flujos Comtrade y ventas de exportación US (ESR)."},{"id":"enterprise","label":"Enterprise","scopes":["series","nowcast","twin","fundamentals","trade","markets","esr"],"rateLimitPerHour":20000,"priceHint":"A medida · SLA","blurb":"Todo Pro + simulador causal AgroTwin, rate limit alto, SLA y datos propietarios (AgriShield). Integración a medida."}],"x-x402":{"enabled":true,"protocol":"x402/1 (https://x402.org)","network":"base-sepolia","asset":"USDC","pricingUsdPerRequest":{"series":0.001,"markets":0.001,"fundamentals":0.005,"trade":0.005,"esr":0.005,"nowcast":0.01,"twin":0.05},"howTo":"Sin API key: GET al endpoint → 402 con `accepts` → pagá y reintentá con el header X-PAYMENT (clientes: @x402/fetch o compatible)."}}