Getting Started

Obtaining Your API Key

1. Log in to your CoinTrail account
2. Ensure you have an active Pro subscription
3. Go to Profile > API Settings
4. Click Generate API Key
5. Copy and securely store your API key

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X GET "https://yourdomain.com/api/v1/markets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Rate Limits

Pro tier API access includes the following limits:

Rate limit headers are included in every response:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9876
X-RateLimit-Reset: 1709251200

Base URL

https://yourdomain.com/api/v1

Response Format

All responses are returned in JSON format:

Success Response

{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "2024-02-01T12:00:00Z",
    "request_id": "abc123"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired."
  }
}

Market Data Endpoints

List All Markets

Get a paginated list of all cryptocurrencies with market data.

GET /api/v1/markets

Query Parameters

Example Request

curl -X GET "https://yourdomain.com/api/v1/markets?per_page=10&order=volume_desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "bitcoin",
      "symbol": "BTC",
      "name": "Bitcoin",
      "current_price": 43250.00,
      "market_cap": 847500000000,
      "market_cap_rank": 1,
      "total_volume": 25600000000,
      "price_change_24h": 1250.50,
      "price_change_percentage_24h": 2.98,
      "circulating_supply": 19600000,
      "ath": 69000.00,
      "atl": 67.81,
      "last_updated": "2024-02-01T12:00:00Z"
    },
    ...
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 25,
    "total_results": 2500
  }
}

Search Markets

Search for cryptocurrencies by name or symbol.

GET /api/v1/markets/search

Query Parameters

Example Request

curl -X GET "https://yourdomain.com/api/v1/markets/search?q=ethereum" \
  -H "Authorization: Bearer YOUR_API_KEY"

Global Stats

Get global cryptocurrency market statistics.

GET /api/v1/markets/global

Example Response

{
  "success": true,
  "data": {
    "total_market_cap": 1750000000000,
    "total_volume_24h": 85000000000,
    "bitcoin_dominance": 48.5,
    "active_cryptocurrencies": 12500,
    "markets": 850,
    "market_cap_change_percentage_24h": 1.25
  }
}

Top Movers

Get top gainers and losers in the last 24 hours.

GET /api/v1/markets/top-movers

Query Parameters

Get Coin Details

Get detailed information about a specific cryptocurrency.

GET /api/v1/coins/{idOrSymbol}

Example Request

curl -X GET "https://yourdomain.com/api/v1/coins/bitcoin" \
  -H "Authorization: Bearer YOUR_API_KEY"

Price History

Get historical price data for a cryptocurrency.

GET /api/v1/coins/{idOrSymbol}/history

Query Parameters

Portfolio Endpoints

List Portfolios

Get all portfolios for the authenticated user.

GET /api/v1/portfolio

Example Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Main Portfolio",
      "total_value": 15250.00,
      "total_cost": 12000.00,
      "profit_loss": 3250.00,
      "profit_loss_percentage": 27.08,
      "holdings_count": 5,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Get Portfolio

Get details of a specific portfolio including holdings.

GET /api/v1/portfolio/{id}

Create Portfolio

Create a new portfolio. Requires write permission.

POST /api/v1/portfolio

Request Body

{
  "name": "DeFi Portfolio",
  "description": "My DeFi investments"
}

Add Holding

Add a cryptocurrency holding to a portfolio.

POST /api/v1/portfolio/{portfolioId}/holdings

Request Body

{
  "coin_id": "bitcoin",
  "quantity": 0.5,
  "buy_price": 42000.00,
  "notes": "DCA purchase"
}

Sell Holding

Record a sell transaction for a holding.

POST /api/v1/holdings/{holdingId}/sell

Request Body

{
  "quantity": 0.25,
  "sell_price": 45000.00,
  "notes": "Taking profits"
}

Get Transactions

Get transaction history for a portfolio.

GET /api/v1/portfolio/{id}/transactions

Sync Portfolio

Sync portfolio with latest market prices.

POST /api/v1/portfolio/{id}/sync

Price Alert Endpoints

List Alerts

Get all price alerts for the authenticated user.

GET /api/v1/alerts

Example Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "coin_id": "bitcoin",
      "coin_symbol": "BTC",
      "target_price": 50000.00,
      "condition": "above",
      "is_active": true,
      "triggered_at": null,
      "created_at": "2024-01-20T14:00:00Z"
    }
  ]
}

Create Alert

Create a new price alert.

POST /api/v1/alerts

Request Body

{
  "coin_id": "ethereum",
  "target_price": 3000.00,
  "condition": "above",
  "notify_email": true
}

Conditions

• above - Trigger when price goes above target
• below - Trigger when price goes below target

Toggle Alert

Enable or disable a price alert.

POST /api/v1/alerts/{id}/toggle

Delete Alert

Delete a price alert.

DELETE /api/v1/alerts/{id}

Error Codes

Code Examples

JavaScript / Node.js

const API_KEY = 'your_api_key';
const BASE_URL = 'https://yourdomain.com/api/v1';

async function getMarkets() {
  const response = await fetch(`${BASE_URL}/markets`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Accept': 'application/json'
    }
  });
  return response.json();
}

async function createAlert(coinId, targetPrice, condition) {
  const response = await fetch(`${BASE_URL}/alerts`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    },
    body: JSON.stringify({
      coin_id: coinId,
      target_price: targetPrice,
      condition: condition
    })
  });
  return response.json();
}

Python

import requests

API_KEY = 'your_api_key'
BASE_URL = 'https://yourdomain.com/api/v1'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Accept': 'application/json'
}

def get_markets():
    response = requests.get(f'{BASE_URL}/markets', headers=headers)
    return response.json()

def get_portfolio(portfolio_id):
    response = requests.get(f'{BASE_URL}/portfolio/{portfolio_id}', headers=headers)
    return response.json()

def create_alert(coin_id, target_price, condition):
    data = {
        'coin_id': coin_id,
        'target_price': target_price,
        'condition': condition
    }
    response = requests.post(f'{BASE_URL}/alerts', headers=headers, json=data)
    return response.json()

PHP

<?php
$apiKey = 'your_api_key';
$baseUrl = 'https://yourdomain.com/api/v1';

function getMarkets() {
    global $apiKey, $baseUrl;

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, "$baseUrl/markets");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $apiKey",
        "Accept: application/json"
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

function getPortfolio($portfolioId) {
    global $apiKey, $baseUrl;

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, "$baseUrl/portfolio/$portfolioId");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $apiKey",
        "Accept: application/json"
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}