Agent API Reference

La superficie pública de Avaltix para integraciones usa un único gateway read-only. Es el mismo contrato que consume el skill oficial de Avaltix para OpenClaw y Claude Code, y es la ruta que debe usarse en onboarding developer-first.

Introducción

El endpoint público recomendado y soportado para integraciones externas es:

POST https://avaltix.io/api/v1/agent/command

Contrato público unificado

El skill, la documentación pública y el onboarding deben hablar del mismo gateway. Las rutas internas /api/v1/* alimentan partes del producto y flujos aprobados, pero no son el contrato público de venta ni de integración.

Host público: https://avaltix.io

No uses api.avaltix.io como host público mientras no exista una entrada DNS operativa para ese subdominio.

Autenticación

Todas las peticiones requieren una Agent API Key en el header Authorization. Las claves se generan desde la cuenta de Avaltix, se almacenan hasheadas, pueden revocarse y están sujetas a scopes, plan y cuotas.

Authorization: Bearer YOUR_API_KEY

Importante: Nunca expongas tu clave en frontend o repositorios públicos. El propio response envelope devuelve metadatos de rate limit y cuota diaria para que tu integración degrade con control.

Request

Ejecuta comandos allowlisted de solo lectura para research, contexto macro y priorización de oportunidades.

Request Body

Parámetro	Tipo	Descripción
command Required	string	Nombre del comando: `snapshot`, `search`, `indicators`, `analyze`, `opportunities`, `macro`, `calendar` o `events`.
args Optional	array	Lista ordenada de argumentos para el comando seleccionado.

Ejemplo

{
  "command": "analyze",
  "args": ["XAUUSD", "1h"]
}

Commands

Los comandos públicos permiten discovery, lectura de indicadores, análisis por activo y contexto cross-asset sin mutar cuenta ni ejecutar operaciones.

Command	Scope	Args	Uso principal
snapshot	market.read	Sin args	Snapshot de mercado cacheado.
search	market.read	query, asset_class opcional	Descubrir símbolos soportados y su estado.
indicators	market.read	symbol, timeframe	Indicadores cacheados por símbolo y timeframe.
analyze	predictions.read	symbol, timeframe	Bias, confianza, drivers e indicadores derivados.
opportunities	predictions.read	limit	Feed priorizado de oportunidades cacheadas.
macro	macro.read	Sin args	Snapshot macro para contexto cross-asset.
calendar	market.read	symbol, user_tz opcional	Calendario de activo y estado de mercado.
events	macro.read	kind, symbol opcional, days opcional	Eventos económicos, earnings, dividendos y crypto.

snapshot

{
  "command": "snapshot",
  "args": []
}

search

{
  "command": "search",
  "args": ["brent", "commodities"]
}

analyze

{
  "command": "analyze",
  "args": ["EURUSD", "4h"]
}

opportunities

{
  "command": "opportunities",
  "args": [5]
}

macro, calendar y events

{
  "command": "macro",
  "args": []
}

{
  "command": "calendar",
  "args": ["WTI", "Europe/Madrid"]
}

{
  "command": "events",
  "args": ["economic", "EURUSD", 14]
}

Response envelope

Todas las respuestas usan el mismo envelope:

{
  "ok": true,
  "data": {},
  "error": null,
  "meta": {
    "request_id": "req_...",
    "generated_at": "2026-04-30T00:00:00+00:00",
    "rate_limit": {},
    "daily_quota": {}
  }
}

Usa meta.rate_limit y meta.daily_quota para controlar retries, fallbacks y degradación por plan desde tu cliente.

Errores

El gateway usa códigos HTTP estándar y mantiene el mismo envelope con ok: false cuando algo falla:

Código	Significado
200	Éxito
400	Comando desconocido o body inválido.
401	Bearer token ausente o Agent API Key inválida.
403	Scope requerido o plan insuficiente.
429	Rate limit o cuota diaria excedida.
503	Gateway temporalmente no disponible.

Formato de error:

{
  "ok": false,
  "data": null,
  "error": {
    "code": "scope_required",
    "message": "This command requires additional scope.",
    "retry_after": 3600
  },
  "meta": {
    "request_id": "req_..."
  }
}

Tooling

La integración pública soportada hoy es el gateway HTTP y el skill oficial de Avaltix para workflows agentic. Si estás integrando desde código, usa un cliente HTTP estándar:

curl -X POST "https://avaltix.io/api/v1/agent/command" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "analyze",
    "args": ["XAUUSD", "1h"]
  }'

Si necesitas una integración institucional adicional, parte de este gateway y de la cobertura real descubierta por search antes de prometer rutas privadas, webhooks o SDKs que no estén publicados.