Referencia de API (Clave API)

Especificaciones técnicas de los endpoints de la API de Minara Agent.

API para desarrolladores

El endpoint principal para interactuar con la IA conversacional de Minara.

Developer Chat

post

Developer chat endpoint supporting streaming, non-streaming, and asynchronous (background) response modes, with optional requestId-based idempotency.

Autorizaciones

BearerAuth

AuthorizationstringRequerido

Format: Authorization: Bearer <YOUR_API_KEY>

Cuerpo

application/json

modestring · enumRequerido

Required. Model mode: 'fast' for quick responses, 'expert' for in-depth analysis.

Valores posibles:

streambooleanOpcional

Optional. Set to true for streaming (SSE), false (default) for standard JSON response. Cannot be combined with background.

Default: false

backgroundbooleanOpcional

Optional. Set to true to run a non-streaming request asynchronously and poll the result later. Requires stream: false.

Default: false

requestIdstring · mín: 1 · máx: 128Opcional

Optional. Client-generated idempotency key, unique within the API key. 1-128 chars matching ^[A-Za-z0-9._:-]+$.

Pattern: ^[A-Za-z0-9._:-]+$

chatIdstringOpcional

Optional. Existing chat to continue. A new chat is created if omitted.

Respuestas

200

Successful response (stream/background not set, or a completed idempotent replay).

application/jsontext/event-stream

idstringOpcional

Server-assigned request id. Present when a requestId was supplied.

requestIdstringOpcional

Your idempotency key, echoed when one was provided.

chatIdstringOpcional

Unique conversation ID.

messageIdstringOpcional

Unique message ID for this response.

contentstringOpcional

The AI-generated response content.

usageobjectOpcional

Usage statistics for the request.

202

Accepted. Returned for background requests, or when an idempotent request is still running.

application/json

400

Bad Request. E.g. combining background=true with stream=true.

401

Unauthorized - Invalid or missing API key

409

Conflict. The requestId was already used with a different request, or has expired and cannot be reused.

post/v1/developer/chat

HTTPcURLJavaScriptPython

POST /v1/developer/chat HTTP/1.1
Host: api-developer.minara.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 127

{
  "mode": "fast",
  "stream": false,
  "background": false,
  "requestId": "text",
  "chatId": "text",
  "message": {
    "role": "user",
    "content": "text"
  }
}

{
  "id": "text",
  "requestId": "text",
  "chatId": "text",
  "messageId": "text",
  "content": "text",
  "usage": {}
}

Get Chat Request Status

get

Retrieve the status and result of any requestId-backed request (sync, stream, or background) by either the server-assigned id or your requestId. Records are retained for 24 hours after reaching a terminal state.

Autorizaciones

BearerAuth

AuthorizationstringRequerido

Format: Authorization: Bearer <YOUR_API_KEY>

Parámetros de ruta

idstringRequerido

The server-assigned id (e.g. bg_abc123) or your requestId. Must use the same API key that created the job.

Respuestas

200

Request status and result (if completed).

application/json

idstringOpcional

Server-assigned request id.

requestIdstringOpcional

Your idempotency key, if one was provided.

chatIdstringOpcional

Chat the request belongs to.

statusstring · enumOpcional

Current lifecycle status of the request.

Valores posibles:

executionModestring · enumOpcional

How the request is being executed.

Valores posibles:

createdAtstring · date-timeOpcional

startedAtstring · date-timeOpcional

completedAtstring · date-timeOpcional

expiresAtstring · date-timeOpcional

When the record is removed (24h after reaching a terminal state).

401

Unauthorized - Invalid or missing API key

404

Not Found. The request does not exist or has expired.

get/v1/developer/chat/requests/{id}

HTTPcURLJavaScriptPython

GET /v1/developer/chat/requests/{id} HTTP/1.1
Host: api-developer.minara.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "requestId": "text",
  "chatId": "text",
  "status": "queued",
  "executionMode": "sync",
  "createdAt": "2026-07-16T14:29:59.015Z",
  "startedAt": "2026-07-16T14:29:59.015Z",
  "completedAt": "2026-07-16T14:29:59.015Z",
  "expiresAt": "2026-07-16T14:29:59.015Z",
  "result": {
    "id": "text",
    "requestId": "text",
    "chatId": "text",
    "messageId": "text",
    "content": "text",
    "usage": {}
  },
  "error": {
    "code": "processing_error",
    "message": "text"
  }
}

Intent to Swap Transaction

post

Convert natural language trading intent into an executable swap transaction payload. Compatible with OKX DEX by default.

Autorizaciones

BearerAuth

AuthorizationstringRequerido

Format: Authorization: Bearer <YOUR_API_KEY>

Cuerpo

application/json

intentstringRequerido

Required. Natural language swap intent (e.g., 'swap 0.1 ETH to USDC').

walletAddressstringRequerido

Required. User wallet address (0x...).

chainstringOpcional

Optional. Chain name (e.g., 'base', 'ethereum', 'bsc', 'arbitrum', 'optimism').

Respuestas

200

Swap transaction generated

application/json

401

Unauthorized - Invalid or missing API key

post/v1/developer/intent-to-swap-tx

HTTPcURLJavaScriptPython

POST /v1/developer/intent-to-swap-tx HTTP/1.1
Host: api-developer.minara.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 109

{
  "intent": "swap 0.1 ETH to USDC",
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
  "chain": "base"
}

{
  "intent": {
    "chain": "base",
    "inputTokenAddress": null,
    "inputTokenSymbol": "ETH",
    "outputTokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "outputTokenSymbol": "USDC",
    "amount": "100000000000000000",
    "userWalletAddress": "0x42a345F3d379B5060f0C36580bAF22C395B1D462"
  },
  "quote": {
    "fromTokenAmount": "100000000000000000",
    "toTokenAmount": "194058559",
    "estimatedGas": "1338000",
    "priceImpact": "-0.03",
    "tradeFee": "0.0174870969512694"
  },
  "inputToken": {
    "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
    "symbol": "ETH",
    "decimals": "18",
    "unitPrice": "1960.63"
  },
  "outputToken": {
    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "symbol": "USDC",
    "decimals": "6",
    "unitPrice": "0.99989"
  },
  "unsignedTx": {
    "chainType": "evm",
    "from": "0x42a345F3d379B5060f0C36580bAF22C395B1D462",
    "to": "0x4409921ae43a39a11d90f7b96cfd0b8093d9fc",
    "data": "0xf2c42696...",
    "value": "100000000000000000",
    "gas": "1338000",
    "gasPrice": "10943011",
    "maxPriorityFeePerGas": "7301883"
  },
  "approval": {
    "isRequired": false,
    "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "spenderAddress": "0x57df6092665eb6058DE53939612413ff4B09114E",
    "requiredAmount": "10000000",
    "approveAmount": "10000000",
    "currentAllowance": "115792089237316195423570985008687907853269984665640564039457584007913129316681",
    "message": "Allowance is sufficient for spender 0x57df6092665eb6058DE53939612413ff4B09114E"
  }
}

Perpetual Trading Suggestion

post

Get AI-powered perpetual trading suggestions with long/short recommendations, entry price, stop loss, take profit levels, and confidence score based on comprehensive market analysis.

Autorizaciones

BearerAuth

AuthorizationstringRequerido

Format: Authorization: Bearer <YOUR_API_KEY>

Cuerpo

application/json

symbolstringRequerido

Required. Trading symbol (e.g., 'BTC', 'ETH', 'SOL').

stylestring · enumOpcional

Optional. Trading style: 'scalping', 'day-trading', or 'swing-trading'. Default: 'scalping'.

Default: scalpingValores posibles:

marginUSDnumberOpcional

Optional. Margin in USD. Default: 1000.

Default: 1000

leveragenumber · mín: 1 · máx: 40Opcional

Optional. Leverage multiplier (max: 40). Default: 10.

Default: 10

strategystringOpcional

Optional. Strategy type. Default: 'max-profit'. More strategies coming soon.

Default: max-profit

Respuestas

200

Perpetual trading suggestion

application/json

entryPricenumberOpcional

Recommended entry price.

sidestring · enumOpcional

Trading side recommendation.

Valores posibles:

stopLossPricenumberOpcional

Recommended stop loss price.

takeProfitPricenumberOpcional

Recommended take profit price.

confidencenumber · máx: 100Opcional

Confidence score (0-100).

reasonsstring[]Opcional

Analysis reasons based on technical indicators.

risksstring[]Opcional

Risk factors to consider.

401

Unauthorized - Invalid or missing API key

post/v1/developer/perp-trading-suggestion

HTTPcURLJavaScriptPython

POST /v1/developer/perp-trading-suggestion HTTP/1.1
Host: api-developer.minara.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 91

{
  "symbol": "text",
  "style": "scalping",
  "marginUSD": 1000,
  "leverage": 10,
  "strategy": "max-profit"
}

{
  "entryPrice": 1,
  "side": "long",
  "stopLossPrice": 1,
  "takeProfitPrice": 1,
  "confidence": 1,
  "reasons": [
    "text"
  ],
  "risks": [
    "text"
  ]
}

Prediction Market Analysis

post

AI-powered prediction market analysis. Analyze prediction market events and get probability estimates for each outcome with detailed reasoning.

Autorizaciones

BearerAuth

AuthorizationstringRequerido

Format: Authorization: Bearer <YOUR_API_KEY>

Cuerpo

application/json

linkstringRequerido

Required. Prediction market page link (e.g., Polymarket event URL).

modestring · enumRequerido

Required. Chat mode: 'fast' or 'expert'.

Valores posibles:

only_resultbooleanOpcional

Optional. Only return prediction probabilities without reasoning. Default: false.

Default: false

customPromptstringOpcional

Optional. Custom instructions to guide the analysis. Use this to specify focus areas, risk preferences, or analysis style.

Respuestas

200

Prediction market analysis

application/json

reasoningstringOpcional

AI reasoning and analysis (empty if only_result=true).

401

Unauthorized - Invalid or missing API key

post/v1/developer/prediction-market-ask

HTTPcURLJavaScriptPython

POST /v1/developer/prediction-market-ask HTTP/1.1
Host: api-developer.minara.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71

{
  "link": "text",
  "mode": "fast",
  "only_result": false,
  "customPrompt": "text"
}

{
  "predictions": [
    {
      "outcome": "text",
      "yesProb": 1,
      "noProb": 1
    }
  ],
  "reasoning": "text"
}

Chat en segundo plano e idempotencia

El chat endpoint anterior admite ejecución asíncrona y reintentos idempotentes mediante dos campos opcionales: background y requestId. Las estructuras de solicitud/respuesta se documentan en el bloque OpenAPI anterior; esta sección cubre las reglas de comportamiento que el esquema no puede expresar.

Ejecución en segundo plano

Establece background: true (solo válido con stream: false) para que la solicitud se acepte de inmediato (202 Accepted) y se procese de forma asíncrona. Consulta periódicamente el endpoint de estado (GET /v1/developer/chat/requests/{id}) con el id (o tu requestIdrequestId background: true con stream: true devuelve 400 Bad Request.

Idempotencia con requestId

requestId es una clave generada por el cliente, única dentro de una sola clave de API, que te permite reintentar de forma segura una solicitud sin generar (ni que se te cobre por) un resultado duplicado. Funciona con los modos síncrono, de streaming y en segundo plano.

• Misma clave, misma carga útil → se reutiliza el trabajo existente. Recuperas su estado/resultado actual en lugar de una nueva generación. Si aún se está ejecutando, recibes 202 Accepted; si ha finalizado, recibes 200 OK con el resultado.
• Misma clave, distinta carga útil → 409 Conflict ("requestId ya se había usado con una solicitud diferente").
• Reutilizar una clave caducada → 409 Conflict ("requestId ha caducado y no puede reutilizarse").

Para solicitudes de streaming que lleven un requestIdrequestId X-Request-Id header, la generación continúa incluso si el cliente se desconecta, y el resultado final puede recuperarse después mediante el endpoint de estado.

Notas sobre el estado de las solicitudes de chat

El endpoint de estado (GET /v1/developer/chat/requests/{id}) acepta tanto el asignado por el servidor id (p. ej. bg_abc123) o tu requestIdrequestId

• Los registros se conservan durante 24 horas después de alcanzar un estado terminal (expiresAt), y luego se eliminan.
• Una búsqueda de solicitud que no existe o ha caducado devuelve 404 Not Found.
• Los trabajos interrumpidos o con tiempo de espera agotado fallan explícitamente (no se reintentan automáticamente). El código de fallo código es uno de processing_error, processing_interrupted, processing_timeout. Envía una nueva solicitud para reintentar.