> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aioka.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Performance
> Historical directional accuracy of each AI Council agent (BTC)
To use the playground, enter your API key in the **X-API-Key** field above.
Don't have a key? [Get one free →](/api-reference/keys/generate)
## Overview
Returns the historical accuracy of each AI Council agent. For every closed BTC
Ghost Trader trade, AIOKA locates the council verdict that triggered it and
checks which agents voted in the direction that actually paid off. The result is
each agent's hit rate across all graded trades.
**Asset:** BTC only — the only asset with a live closed-trade record.
**Tier:** Free ✅
**Cache TTL:** 3600 seconds (1 hour)
## How accuracy is graded
Each closed trade's outcome direction is derived from its result and direction:
| Trade | Outcome | Correct vote |
| ---------- | ---------- | ------------ |
| LONG win | price rose | `BULLISH` |
| LONG loss | price fell | `BEARISH` |
| SHORT win | price fell | `BEARISH` |
| SHORT loss | price rose | `BULLISH` |
Only directional votes (`BULLISH` / `BEARISH`) are graded. `NEUTRAL` votes and
non-directional rulings (e.g. RISK SHIELD's `PROCEED` / `REDUCE` / `WAIT` /
`AVOID`) carry no directional claim, so they are excluded from the denominator
rather than counted as wrong. An agent with no directional history is omitted
from the response.
## Response Fields
| Field | Type | Description |
| ------------------------ | -------------- | -------------------------------------------------------- |
| `asset` | string | Always `"BTC"`. |
| `trades_analyzed` | number | Count of closed BTC trades matched to a council verdict. |
| `agents` | array | Per-agent accuracy entries (see below). May be empty. |
| `agents[].agent_name` | string | Display name, e.g. `"CHAIN ORACLE"`. |
| `agents[].correct_calls` | number | Directional votes that matched the outcome. |
| `agents[].total_calls` | number | Directional votes graded for this agent. |
| `agents[].accuracy_pct` | number | `correct_calls / total_calls × 100`, 1 decimal. |
| `agents[].last_updated` | string \| null | ISO timestamp of the most recent graded trade. |
| `cached` | boolean | Whether this response was served from cache. |
| `cache_ttl_seconds` | number | Cache lifetime in seconds (3600). |
Accuracy is computed only from BTC trades because BTC is the only asset with a
validated, closed-trade record. Other asset councils (ETH, SOL, etc.) do not
yet expose accuracy stats.
## OpenAPI
````yaml GET /v1/agents/performance
openapi: 3.1.0
info:
title: AIOKA Intelligence API
description: |
## AI-powered crypto market intelligence
AIOKA Intelligence API provides real-time access to our AI Council verdicts,
market signals, regime detection, and Ghost Trader entry signals.
### Tiers
- **Free**: 100 calls/day — Verdict + Regime
- **Basic** ($49/mo): 1,000 calls/day — + Signals
- **Pro** ($199/mo): 10,000 calls/day — + Council + Ghost
### Authentication
Pass your API key in the `X-API-Key` header:
```
X-API-Key: aik_free_xxxxxxxxxxxx
```
### Get your API key
`POST /v1/keys/generate` (free tier, no credit card)
contact:
name: AIOKA Support
url: https://docs.aioka.io/
email: api@aioka.io
license:
name: Commercial
url: https://aioka.io/terms
version: 1.0.0
servers:
- url: https://api.aioka.io
description: Production — AIOKA Intelligence API
security: []
paths:
/v1/agents/performance:
get:
tags:
- Agents
summary: AI Council Agent Accuracy
description: >-
Per-agent historical accuracy for the BTC AI Council.
For every closed BTC Ghost Trader trade, AIOKA finds the council verdict
that
triggered it and checks which agents voted in the direction that
actually paid
off. The result is each agent's hit rate across all graded trades.
Only directional votes (BULLISH / BEARISH) are graded. NEUTRAL votes and
non-directional rulings (RISK SHIELD) are excluded from the denominator,
so an
agent with no directional history simply has `total_calls: 0` and is
omitted.
**Asset:** BTC only (the only asset with a live closed-trade record).
**Tier:** Free ✅
**Cache TTL:** 3600 seconds (1 hour)
**Rate limit:** 100 calls/day, 2/minute (Free tier)
operationId: get_agent_performance_v1_agents_performance_get
responses:
'200':
description: Per-agent accuracy stats
content:
application/json:
schema:
$ref: '#/components/schemas/AgentPerformanceResponse'
'401':
description: Invalid or missing API key
'429':
description: Rate limit exceeded
security:
- APIKeyHeader: []
components:
schemas:
AgentPerformanceResponse:
properties:
asset:
type: string
title: Asset
trades_analyzed:
type: integer
title: Trades Analyzed
agents:
items:
$ref: '#/components/schemas/AgentPerformanceItem'
type: array
title: Agents
cached:
type: boolean
title: Cached
cache_ttl_seconds:
type: integer
title: Cache Ttl Seconds
type: object
required:
- asset
- trades_analyzed
- agents
- cached
- cache_ttl_seconds
title: AgentPerformanceResponse
description: '`/v1/agents/performance` — per-agent accuracy across closed BTC trades.'
example:
agents:
- accuracy_pct: 77.8
agent_name: CHAIN ORACLE
correct_calls: 14
last_updated: '2026-05-20T14:32:00Z'
total_calls: 18
- accuracy_pct: 64.7
agent_name: TECH HAWK
correct_calls: 11
last_updated: '2026-05-20T14:32:00Z'
total_calls: 17
asset: BTC
cache_ttl_seconds: 3600
cached: true
trades_analyzed: 18
AgentPerformanceItem:
properties:
agent_name:
type: string
title: Agent Name
correct_calls:
type: integer
title: Correct Calls
total_calls:
type: integer
title: Total Calls
accuracy_pct:
type: number
title: Accuracy Pct
last_updated:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Updated
type: object
required:
- agent_name
- correct_calls
- total_calls
- accuracy_pct
title: AgentPerformanceItem
description: Historical accuracy of a single AI Council agent (BTC only).
securitySchemes:
APIKeyHeader:
type: apiKey
description: 'Your AIOKA Intelligence API key (format: aik_{tier}_{random})'
in: header
name: X-API-Key
````