Tinkoff Investments API

Portfolio and stock management API for Tinkoff Investments platform.

Base URL: api.koveh.com/tinkoff-investments/ or api.koveh.com/t/

Endpoints

Method	Endpoint	Description
GET	`/health`	Service health check
GET	`/accounts`	Get investment accounts
GET	`/stocks`	Get available stocks
GET	`/portfolio/{account_id}`	Get portfolio for account
GET	`/models`	Get available models

Authentication

All endpoints require Bearer token authentication:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "api.koveh.com/t/accounts"

Get Investment Accounts

Get list of investment accounts for the authenticated user.

Endpoint: GET /accounts

Response

[
  {
    "id": "account-123",
    "name": "Main Investment Account",
    "type": "TINKOFF",
    "status": "ACTIVE",
    "currency": "RUB",
    "balance": {
      "total": 100000.50,
      "available": 50000.25,
      "blocked": 0.00
    },
    "created_at": "2023-01-15T10:30:00Z"
  }
]

Example Request

curl -X GET "api.koveh.com/t/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Available Stocks

Get list of available stocks for trading.

Endpoint: GET /stocks

Query Parameters

limit (number, optional): Number of stocks to return. Default: 100
offset (number, optional): Number of stocks to skip. Default: 0
search (string, optional): Search by ticker or company name
currency (string, optional): Filter by currency (RUB, USD, EUR)

Response

[
  {
    "ticker": "AAPL",
    "name": "Apple Inc.",
    "currency": "USD",
    "exchange": "NASDAQ",
    "sector": "Technology",
    "current_price": 150.25,
    "change_percent": 2.5,
    "volume": 50000000,
    "market_cap": 2500000000000
  },
  {
    "ticker": "SBER",
    "name": "Sberbank of Russia",
    "currency": "RUB",
    "exchange": "MOEX",
    "sector": "Financial Services",
    "current_price": 250.75,
    "change_percent": -1.2,
    "volume": 10000000,
    "market_cap": 5000000000000
  }
]

Example Request

curl -X GET "api.koveh.com/t/stocks?limit=10&currency=USD" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Portfolio

Get portfolio information for a specific account.

Endpoint: GET /portfolio/{account_id}

Path Parameters

account_id (string, required): ID of the investment account

Response

{
  "account_id": "account-123",
  "account_name": "Main Investment Account",
  "total_value": 150000.75,
  "currency": "RUB",
  "positions": [
    {
      "ticker": "AAPL",
      "name": "Apple Inc.",
      "quantity": 10,
      "average_price": 145.50,
      "current_price": 150.25,
      "market_value": 1502.50,
      "unrealized_pnl": 47.50,
      "unrealized_pnl_percent": 3.26,
      "currency": "USD"
    },
    {
      "ticker": "SBER",
      "name": "Sberbank of Russia",
      "quantity": 100,
      "average_price": 240.00,
      "current_price": 250.75,
      "market_value": 25075.00,
      "unrealized_pnl": 1075.00,
      "unrealized_pnl_percent": 4.48,
      "currency": "RUB"
    }
  ],
  "summary": {
    "total_positions": 2,
    "total_unrealized_pnl": 1122.50,
    "total_unrealized_pnl_percent": 3.87,
    "currencies": ["USD", "RUB"]
  },
  "last_updated": "2025-08-30T09:19:31.245295"
}

Example Request

curl -X GET "api.koveh.com/t/portfolio/account-123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Health Check

Check service health and Tinkoff connection status.

Endpoint: GET /health

Response

{
  "status": "healthy",
  "tinkoff_connected": true,
  "rabbitmq_connected": true,
  "timestamp": "2025-08-30T09:19:31.245295"
}

Get Available Models

Get list of available models and features.

Endpoint: GET /models

Response

[
  {
    "id": "portfolio-analysis",
    "name": "Portfolio Analysis",
    "description": "AI-powered portfolio analysis and recommendations",
    "features": [
      "Risk assessment",
      "Diversification analysis",
      "Performance prediction"
    ]
  },
  {
    "id": "stock-prediction",
    "name": "Stock Prediction",
    "description": "Machine learning models for stock price prediction",
    "features": [
      "Technical analysis",
      "Sentiment analysis",
      "Price forecasting"
    ]
  }
]

Error Responses

{
  "error": "Account not found",
  "status_code": 404,
  "timestamp": "2025-08-30T09:19:31.245295"
}

Rate Limiting

Limit: 100 requests per minute
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Integration Example

Portfolio Analysis with AI

import requests

# Get portfolio information
portfolio_response = requests.get(
    "http://api.koveh.com/t/portfolio/account-123",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
portfolio = portfolio_response.json()

# Analyze portfolio with AI
analysis_response = requests.post(
    "http://api.koveh.com/qwen3/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "messages": [
            {"role": "user", "content": f"Analyze this portfolio and provide recommendations: {portfolio}"}
        ]
    }
)

print(analysis_response.json()['choices'][0]['message']['content'])

Supported Features

Account Management

View account balances
Account status monitoring
Multi-currency support

Portfolio Tracking

Real-time position tracking
Unrealized P&L calculation
Performance metrics

Stock Information

Real-time stock prices
Company information
Market data

AI Integration

Portfolio analysis
Stock recommendations
Risk assessment

Tinkoff Investments API

On this page