> For the complete documentation index, see [llms.txt](https://minara.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://minara.ai/docs/minara-handbook/ko/trade/agent-api/api-reference-api-key.md).

# API 참고 문서(API 키)

Minara Agent API 엔드포인트에 대한 기술 사양.

### 개발자 API

Minara의 대화형 AI와 상호작용하기 위한 핵심 엔드포인트.

## Developer Chat

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

```json
{"openapi":"3.0.0","info":{"title":"Minara Agent API","version":"1.0"},"servers":[{"url":"https://api-developer.minara.ai"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API-KEY","description":"Format: Authorization: Bearer <YOUR_API_KEY>"}},"schemas":{"ChatRequest":{"type":"object","required":["mode","message"],"properties":{"mode":{"type":"string","enum":["fast","expert"],"description":"Required. Model mode: 'fast' for quick responses, 'expert' for in-depth analysis."},"stream":{"type":"boolean","default":false,"description":"Optional. Set to true for streaming (SSE), false (default) for standard JSON response. Cannot be combined with background."},"background":{"type":"boolean","default":false,"description":"Optional. Set to true to run a non-streaming request asynchronously and poll the result later. Requires stream: false."},"requestId":{"type":"string","pattern":"^[A-Za-z0-9._:-]+$","minLength":1,"maxLength":128,"description":"Optional. Client-generated idempotency key, unique within the API key. 1-128 chars matching ^[A-Za-z0-9._:-]+$."},"chatId":{"type":"string","description":"Optional. Existing chat to continue. A new chat is created if omitted."},"message":{"$ref":"#/components/schemas/Message"}}},"Message":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user"],"description":"Required. Message sender role, must be 'user'."},"content":{"type":"string","description":"Required. The user's query content."}}},"ChatResponse":{"type":"object","properties":{"id":{"type":"string","description":"Server-assigned request id. Present when a requestId was supplied."},"requestId":{"type":"string","description":"Your idempotency key, echoed when one was provided."},"chatId":{"type":"string","description":"Unique conversation ID."},"messageId":{"type":"string","description":"Unique message ID for this response."},"content":{"type":"string","description":"The AI-generated response content."},"usage":{"type":"object","description":"Usage statistics for the request."}}},"ChatAcceptedResponse":{"type":"object","properties":{"id":{"type":"string","description":"Server-assigned request id (e.g. bg_abc123)."},"requestId":{"type":"string","description":"Your idempotency key, if one was provided."},"chatId":{"type":"string","description":"Chat the request belongs to."},"status":{"type":"string","enum":["queued"],"description":"Initial status of the accepted asynchronous request."}}}}},"paths":{"/v1/developer/chat":{"post":{"summary":"Developer Chat","description":"Developer chat endpoint supporting streaming, non-streaming, and asynchronous (background) response modes, with optional requestId-based idempotency.","operationId":"developerChat","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}}},"responses":{"200":{"description":"Successful response (stream/background not set, or a completed idempotent replay).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"}},"text/event-stream":{"schema":{"type":"string","description":"Server-Sent Events (SSE) stream. Each event line starts with `data:`.\nThe final message is formed by concatenating chunk/delta content in order.\n"}}}},"202":{"description":"Accepted. Returned for background requests, or when an idempotent request is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAcceptedResponse"}}}},"400":{"description":"Bad Request. E.g. combining background=true with stream=true."},"401":{"description":"Unauthorized - Invalid or missing API key"},"409":{"description":"Conflict. The requestId was already used with a different request, or has expired and cannot be reused."}}}}}}
```

## Get Chat Request Status

> 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.

```json
{"openapi":"3.0.0","info":{"title":"Minara Agent API","version":"1.0"},"servers":[{"url":"https://api-developer.minara.ai"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API-KEY","description":"Format: Authorization: Bearer <YOUR_API_KEY>"}},"schemas":{"ChatRequestStatus":{"type":"object","properties":{"id":{"type":"string","description":"Server-assigned request id."},"requestId":{"type":"string","description":"Your idempotency key, if one was provided."},"chatId":{"type":"string","description":"Chat the request belongs to."},"status":{"type":"string","enum":["queued","in_progress","completed","failed"],"description":"Current lifecycle status of the request."},"executionMode":{"type":"string","enum":["sync","stream","background"],"description":"How the request is being executed."},"createdAt":{"type":"string","format":"date-time"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","description":"When the record is removed (24h after reaching a terminal state)."},"result":{"$ref":"#/components/schemas/ChatResponse"},"error":{"type":"object","description":"Present when status is 'failed'.","properties":{"code":{"type":"string","enum":["processing_error","processing_interrupted","processing_timeout"],"description":"Failure code."},"message":{"type":"string"}}}}},"ChatResponse":{"type":"object","properties":{"id":{"type":"string","description":"Server-assigned request id. Present when a requestId was supplied."},"requestId":{"type":"string","description":"Your idempotency key, echoed when one was provided."},"chatId":{"type":"string","description":"Unique conversation ID."},"messageId":{"type":"string","description":"Unique message ID for this response."},"content":{"type":"string","description":"The AI-generated response content."},"usage":{"type":"object","description":"Usage statistics for the request."}}}}},"paths":{"/v1/developer/chat/requests/{id}":{"get":{"summary":"Get Chat Request Status","description":"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.","operationId":"getChatRequestStatus","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The server-assigned id (e.g. bg_abc123) or your requestId. Must use the same API key that created the job."}],"responses":{"200":{"description":"Request status and result (if completed).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequestStatus"}}}},"401":{"description":"Unauthorized - Invalid or missing API key"},"404":{"description":"Not Found. The request does not exist or has expired."}}}}}}
```

## Intent to Swap Transaction

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

```json
{"openapi":"3.0.0","info":{"title":"Minara Agent API","version":"1.0"},"servers":[{"url":"https://api-developer.minara.ai"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API-KEY","description":"Format: Authorization: Bearer <YOUR_API_KEY>"}},"schemas":{"IntentToSwapRequest":{"type":"object","required":["intent","walletAddress"],"properties":{"intent":{"type":"string","description":"Required. Natural language swap intent (e.g., 'swap 0.1 ETH to USDC')."},"walletAddress":{"type":"string","description":"Required. User wallet address (0x...)."},"chain":{"type":"string","description":"Optional. Chain name (e.g., 'base', 'ethereum', 'bsc', 'arbitrum', 'optimism')."}}},"SwapTransactionResponse":{"type":"object","properties":{"intent":{"type":"object","description":"Parsed user intent","properties":{"chain":{"type":"string","description":"Chain name (e.g., 'base')."},"inputTokenAddress":{"type":"string","nullable":true,"description":"Input token contract address (null for native token)."},"inputTokenSymbol":{"type":"string","description":"Input token symbol (e.g., 'ETH')."},"outputTokenAddress":{"type":"string","description":"Output token contract address."},"outputTokenSymbol":{"type":"string","description":"Output token symbol (e.g., 'USDC')."},"amount":{"type":"string","description":"Token amount in wei/smallest unit."},"userWalletAddress":{"type":"string","description":"User's wallet address."}}},"quote":{"type":"object","description":"Swap quote and pricing information","properties":{"fromTokenAmount":{"type":"string","description":"Input token amount in smallest unit."},"toTokenAmount":{"type":"string","description":"Expected output token amount in smallest unit."},"estimatedGas":{"type":"string","description":"Estimated gas cost for the transaction."},"priceImpact":{"type":"string","description":"Price impact percentage."},"tradeFee":{"type":"string","description":"Trading fee amount."}}},"inputToken":{"type":"object","description":"Input token details","properties":{"address":{"type":"string","description":"Token contract address."},"symbol":{"type":"string","description":"Token symbol."},"decimals":{"type":"string","description":"Token decimals."},"unitPrice":{"type":"string","description":"Token unit price in USD."}}},"outputToken":{"type":"object","description":"Output token details","properties":{"address":{"type":"string","description":"Token contract address."},"symbol":{"type":"string","description":"Token symbol."},"decimals":{"type":"string","description":"Token decimals."},"unitPrice":{"type":"string","description":"Token unit price in USD."}}},"unsignedTx":{"type":"object","description":"Unsigned transaction ready to be signed and broadcasted","properties":{"chainType":{"type":"string","description":"Chain type (e.g., 'evm')."},"from":{"type":"string","description":"Sender address."},"to":{"type":"string","description":"Contract address to call."},"data":{"type":"string","description":"Encoded transaction data."},"value":{"type":"string","description":"Native token value to send (in wei)."},"gas":{"type":"string","description":"Gas limit."},"gasPrice":{"type":"string","description":"Gas price (legacy)."},"maxPriorityFeePerGas":{"type":"string","description":"Max priority fee per gas (EIP-1559)."}}},"approval":{"type":"object","description":"Token approval information (required for ERC20 token swaps)","properties":{"isRequired":{"type":"boolean","description":"Whether token approval is required before swap."},"tokenAddress":{"type":"string","description":"Token contract address that needs approval."},"spenderAddress":{"type":"string","description":"Spender address (DEX router) that needs approval."},"requiredAmount":{"type":"string","description":"Minimum token amount that needs to be approved."},"approveAmount":{"type":"string","description":"Recommended approval amount."},"currentAllowance":{"type":"string","description":"Current approved allowance for the spender."},"message":{"type":"string","description":"Human-readable approval status message."}}}}}}},"paths":{"/v1/developer/intent-to-swap-tx":{"post":{"summary":"Intent to Swap Transaction","description":"Convert natural language trading intent into an executable swap transaction payload. Compatible with OKX DEX by default.","operationId":"intentToSwap","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntentToSwapRequest"}}}},"responses":{"200":{"description":"Swap transaction generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapTransactionResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing API key"}}}}}}
```

## Perpetual Trading Suggestion

> 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.

```json
{"openapi":"3.0.0","info":{"title":"Minara Agent API","version":"1.0"},"servers":[{"url":"https://api-developer.minara.ai"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API-KEY","description":"Format: Authorization: Bearer <YOUR_API_KEY>"}},"schemas":{"PerpTradingRequest":{"type":"object","required":["symbol"],"properties":{"symbol":{"type":"string","description":"Required. Trading symbol (e.g., 'BTC', 'ETH', 'SOL')."},"style":{"type":"string","enum":["scalping","day-trading","swing-trading"],"default":"scalping","description":"Optional. Trading style: 'scalping', 'day-trading', or 'swing-trading'. Default: 'scalping'."},"marginUSD":{"type":"number","default":1000,"description":"Optional. Margin in USD. Default: 1000."},"leverage":{"type":"number","default":10,"minimum":1,"maximum":40,"description":"Optional. Leverage multiplier (max: 40). Default: 10."},"strategy":{"type":"string","default":"max-profit","description":"Optional. Strategy type. Default: 'max-profit'. More strategies coming soon."}}},"PerpTradingResponse":{"type":"object","properties":{"entryPrice":{"type":"number","description":"Recommended entry price."},"side":{"type":"string","enum":["long","short"],"description":"Trading side recommendation."},"stopLossPrice":{"type":"number","description":"Recommended stop loss price."},"takeProfitPrice":{"type":"number","description":"Recommended take profit price."},"confidence":{"type":"number","minimum":0,"maximum":100,"description":"Confidence score (0-100)."},"reasons":{"type":"array","items":{"type":"string"},"description":"Analysis reasons based on technical indicators."},"risks":{"type":"array","items":{"type":"string"},"description":"Risk factors to consider."}}}}},"paths":{"/v1/developer/perp-trading-suggestion":{"post":{"summary":"Perpetual Trading Suggestion","description":"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.","operationId":"perpTradingSuggestion","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpTradingRequest"}}}},"responses":{"200":{"description":"Perpetual trading suggestion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpTradingResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing API key"}}}}}}
```

## Prediction Market Analysis

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

```json
{"openapi":"3.0.0","info":{"title":"Minara Agent API","version":"1.0"},"servers":[{"url":"https://api-developer.minara.ai"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API-KEY","description":"Format: Authorization: Bearer <YOUR_API_KEY>"}},"schemas":{"PredictionMarketRequest":{"type":"object","required":["link","mode"],"properties":{"link":{"type":"string","description":"Required. Prediction market page link (e.g., Polymarket event URL)."},"mode":{"type":"string","enum":["fast","expert"],"description":"Required. Chat mode: 'fast' or 'expert'."},"only_result":{"type":"boolean","default":false,"description":"Optional. Only return prediction probabilities without reasoning. Default: false."},"customPrompt":{"type":"string","description":"Optional. Custom instructions to guide the analysis. Use this to specify focus areas, risk preferences, or analysis style."}}},"PredictionMarketResponse":{"type":"object","properties":{"predictions":{"type":"array","description":"Array of prediction outcomes. Each outcome represents an event option with its yes/no probabilities.","items":{"type":"object","properties":{"outcome":{"type":"string","description":"Outcome name (event option, e.g., candidate name, team name)."},"yesProb":{"type":"number","description":"Probability of YES for this outcome (0-1)."},"noProb":{"type":"number","description":"Probability of NO for this outcome (0-1)."}}}},"reasoning":{"type":"string","description":"AI reasoning and analysis (empty if only_result=true)."}}}}},"paths":{"/v1/developer/prediction-market-ask":{"post":{"summary":"Prediction Market Analysis","description":"AI-powered prediction market analysis. Analyze prediction market events and get probability estimates for each outcome with detailed reasoning.","operationId":"predictionMarketAsk","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictionMarketRequest"}}}},"responses":{"200":{"description":"Prediction market analysis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictionMarketResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing API key"}}}}}}
```

## The Message object

```json
{"openapi":"3.0.0","info":{"title":"Minara Agent API","version":"1.0"},"components":{"schemas":{"Message":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user"],"description":"Required. Message sender role, must be 'user'."},"content":{"type":"string","description":"Required. The user's query content."}}}}}}
```

## The ChatResponse object

```json
{"openapi":"3.0.0","info":{"title":"Minara Agent API","version":"1.0"},"components":{"schemas":{"ChatResponse":{"type":"object","properties":{"chatId":{"type":"string","description":"Unique conversation ID."},"messageId":{"type":"string","description":"Unique message ID for this response."},"content":{"type":"string","description":"The AI-generated response content."},"usage":{"type":"object","description":"Usage statistics for the request."}}}}}}
```

## 백그라운드 채팅 및 멱등성

해당 `채팅` 위 엔드포인트는 두 개의 선택적 필드를 통해 비동기 실행과 멱등 재시도를 지원합니다: `백그라운드` 그리고 `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`. 재시도하려면 새 요청을 제출하세요.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://minara.ai/docs/minara-handbook/ko/trade/agent-api/api-reference-api-key.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.