API 参考文档（API 密钥）

Minara Agent API 端点的技术规范。

开发者 API

与 Minara 对话式 AI 交互的核心端点。

Developer Chat

post

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

授权

Authorizationstring必填

Format: Authorization: Bearer <YOUR_API_KEY>

请求体

modestring · enum必填

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

可能的值:

streamboolean可选

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

Default: false

backgroundboolean可选

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

Default: false

requestIdstring · 最小值: 1 · 最大值: 128可选

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

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

chatIdstring可选

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

响应

200

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

idstring可选

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

requestIdstring可选

Your idempotency key, echoed when one was provided.

chatIdstring可选

Unique conversation ID.

messageIdstring可选

Unique message ID for this response.

contentstring可选

The AI-generated response content.

usageobject可选

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

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.

授权

Authorizationstring必填

Format: Authorization: Bearer <YOUR_API_KEY>

路径参数

idstring必填

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

响应

200

Request status and result (if completed).

application/json

idstring可选

Server-assigned request id.

requestIdstring可选

Your idempotency key, if one was provided.

chatIdstring可选

Chat the request belongs to.

statusstring · enum可选

Current lifecycle status of the request.

可能的值:

executionModestring · enum可选

How the request is being executed.

可能的值:

createdAtstring · date-time可选

startedAtstring · date-time可选

completedAtstring · date-time可选

expiresAtstring · date-time可选

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}

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-16T13:34:00.258Z",
  "startedAt": "2026-07-16T13:34:00.258Z",
  "completedAt": "2026-07-16T13:34:00.258Z",
  "expiresAt": "2026-07-16T13:34:00.258Z",
  "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.

授权

Authorizationstring必填

Format: Authorization: Bearer <YOUR_API_KEY>

请求体

intentstring必填

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

walletAddressstring必填

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

chainstring可选

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

响应

200

Swap transaction generated

application/json

401

Unauthorized - Invalid or missing API key

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

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.

授权

Authorizationstring必填

Format: Authorization: Bearer <YOUR_API_KEY>

请求体

symbolstring必填

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

stylestring · enum可选

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

Default: scalping可能的值:

marginUSDnumber可选

Optional. Margin in USD. Default: 1000.

Default: 1000

leveragenumber · 最小值: 1 · 最大值: 40可选

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

Default: 10

strategystring可选

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

Default: max-profit

响应

200

Perpetual trading suggestion

application/json

entryPricenumber可选

Recommended entry price.

sidestring · enum可选

Trading side recommendation.

可能的值:

stopLossPricenumber可选

Recommended stop loss price.

takeProfitPricenumber可选

Recommended take profit price.

confidencenumber · 最大值: 100可选

Confidence score (0-100).

reasonsstring[]可选

Analysis reasons based on technical indicators.

risksstring[]可选

Risk factors to consider.

401

Unauthorized - Invalid or missing API key

post/v1/developer/perp-trading-suggestion

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.

授权

Authorizationstring必填

Format: Authorization: Bearer <YOUR_API_KEY>

请求体

linkstring必填

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

modestring · enum必填

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

可能的值:

only_resultboolean可选

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

Default: false

customPromptstring可选

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

响应

200

Prediction market analysis

application/json

reasoningstring可选

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

401

Unauthorized - Invalid or missing API key

post/v1/developer/prediction-market-ask

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"
}

后台聊天与幂等性

该 聊天 上述端点通过两个可选字段支持异步执行和幂等重试： 后台 和 requestId。请求/响应结构已在上方的 OpenAPI 块中记录；本节涵盖架构无法表达的行为规则。

后台执行

设置 background: true （仅在与 stream: false）以便请求立即被接受（202 Accepted）并异步处理。轮询状态端点（GET /v1/developer/chat/requests/{id}），使用返回的 id （或你的 requestId），直到其到达终态。将 background: true 与 stream: true 会返回 400 Bad Request.

幂等性 `requestId`

requestId 是客户端生成的密钥，且在 单个 API 密钥内唯一，可让你安全地重试请求，而不会生成（并因此产生计费的）重复结果。它适用于同步、流式和后台模式。

相同密钥，相同负载 → 复用现有任务。你会返回其当前状态/结果，而不是重新生成。如果它仍在运行，你会收到 202 Accepted；如果它已完成，你会收到 200 OK 及其结果。
相同密钥，不同负载 → 409 Conflict (“requestId 已与不同请求一起使用”).
重复使用已过期的密钥 → 409 Conflict (“requestId 已过期，无法重复使用”).

对于携带 requestId的流式请求，响应包含一个 X-Request-Id 头，即使客户端断开连接，生成也会继续，之后可通过状态端点获取最终结果。

聊天请求状态说明

状态端点（GET /v1/developer/chat/requests/{id}）接受服务器分配的 id （例如 bg_abc123）或你的 requestId，并且必须使用创建该任务的同一个 API 密钥。

记录保留 24 小时 ，在到达终态（expiresAt）后保留，然后删除。
不存在或已过期的请求查询会返回 404 Not Found.
中断或超时的任务会明确失败（它们不会自动重试）。失败 代码 是以下之一： processing_error, processing_interrupted, processing_timeout。提交新请求以重试。

上一页x402 下一页API 参考文档（x402）

最后更新于 2天前

这有帮助吗？

下午好

开发者 API

Developer Chat

Get Chat Request Status

Intent to Swap Transaction

Perpetual Trading Suggestion

Prediction Market Analysis

后台聊天与幂等性

后台执行

幂等性 requestId

聊天请求状态说明

幂等性 `requestId`