Reference

API Reference

Endpoint reference for Turnqey API v2026.04.1, rendered from the public OpenAPI spec.

OpenAPI-backed reference

This reference is rendered from the Turnqey OpenAPI 3.1 specification, keeping the documented endpoints, schemas, and SDK generation source in one production-owned file: openapi/turnqey.yaml.

Servers

https://api.turnqey.xyz - Turnqey API - Production (use /v1/api/* paths)
https://qscore.turnqey.xyz - QScore API - Production (use /api/* paths)
https://sandbox.turnqey.xyz - Sandbox

Auth

Bearer-token issuance for the Turnqey API.

POST/v1/api/tokenAuth

Generate authentication token

Creates a new JWT token using client credentials. Tokens are valid for one hour - call this endpoint hourly to rotate.

Request body

application/json

{
  "clientId": "tnq_client_01HVYX",
  "clientSecret": "••••••••"
}

Responses

200Token issued

application/json

{
  "isError": false,
  "message": "Success",
  "result": {
    "accessToken": "eyJhbGciOiJIUzI1Ni…",
    "expiresIn": 3600,
    "tokenType": "Bearer"
  },
  "statusCode": 200
}

401Invalid client credentials.

Accounts

Cryptoasset accounts, identity lookups, transactions, and balances.

GET/v1/api/account/collection/{collectionId}Accounts

Get account collection by ID

Retrieves account information for a specific collection identified by its UUID.

Parameters

Name	In	Type	Required	Description
`collectionId`	path	string (uuid)	Yes	UUID of the account collection.

Responses

200Account collection

application/json

{
  "isError": false,
  "message": "Success",
  "result": {
    "accountId": "12345678-e89b-12d3-a456-426614174000",
    "collectionId": "98765432-e89b-12d3-a456-426614174000",
    "platform": "coinbase",
    "createdOn": "2024-08-01T00:00:00Z"
  },
  "statusCode": 200
}

401Unauthorized - bearer token missing or invalid.

404Collection not found.

GET/v1/api/account/identity/{identity}Accounts

Get account by identity

Retrieves account information for a specific identity string (e.g. external advisor identifier).

Parameters

Name	In	Type	Required	Description
`identity`	path	string	Yes	Identity string used by the partner system.

Responses

200Account record

application/json

{
  "isError": false,
  "message": "Success",
  "result": {
    "accountId": "12345678-e89b-12d3-a456-426614174000",
    "identity": "advisor_42",
    "platform": "kraken"
  },
  "statusCode": 200
}

401Unauthorized.

404Identity not found.

GET/v1/api/account/{accountId}/transactionsAccounts

Get account transactions

Retrieves transaction history for a specific account identified by its UUID.

Parameters

Name	In	Type	Required	Description
`accountId`	path	string (uuid)	Yes	UUID of the account.
`from`	query	string (date)	No	Inclusive start date (ISO-8601).
`to`	query	string (date)	No	Inclusive end date (ISO-8601).

Responses

200Transaction history

application/json

{
  "isError": false,
  "message": "Success",
  "result": {
    "transactions": [
      {
        "transactionId": "tx_01HVYX",
        "symbol": "BTC",
        "direction": "buy",
        "amount": "0.5",
        "price": "49000.00",
        "timestamp": "2024-09-12T15:04:05Z"
      }
    ]
  },
  "statusCode": 200
}

401Unauthorized.

GET/v1/api/account/{accountId}/balancesAccounts

Get account balances

Retrieves current balances for a specific account identified by its UUID.

Parameters

Name	In	Type	Required	Description
`accountId`	path	string (uuid)	Yes	UUID of the account.
`forceRefresh`	query	boolean	No	Force a refresh from the source if cached data is older than 30 minutes.

Responses

200Account balances

application/json

{
  "isError": false,
  "message": "Success",
  "result": {
    "balances": [
      {
        "symbol": "BTC",
        "balance": "0.5",
        "costBasis": "24500.00",
        "marketValue": "25000.00",
        "realizedGainLoss": "500.00",
        "unrealizedGainLoss": "500.00"
      }
    ],
    "lastUpdatedOn": "2024-09-12T15:04:05Z",
    "marketValue": "25000.00",
    "realizedGainLoss": "500.00",
    "unrealizedGainLoss": "500.00"
  },
  "statusCode": 200
}

401Unauthorized.

422Unprocessable entity.

Integrity

Data checksum endpoints used for partner reconciliation.

GET/v1/api/checksumIntegrity

Get data checksum

Retrieves a checksum for data verification, filtered by platform, collection, or identity.

Parameters

Name	In	Type	Required	Description
`platform`	query	string	No	Filter by source platform (e.g. coinbase, kraken).
`collectionId`	query	string (uuid)	No	Filter by account collection.
`identity`	query	string	No	Filter by external identity string.

Responses

200Checksum payload

application/json

{
  "isError": false,
  "message": "Success",
  "result": {
    "checksum": "f3a1c0b9d4e8…",
    "computedAt": "2024-09-12T15:04:05Z",
    "rowCount": 4218
  },
  "statusCode": 200
}

401Unauthorized.

Cryptoassets

Market data, prices, and reference info for tracked cryptocurrencies.

GET/api/crypto-data/{symbols}Cryptoassets

Get cryptocurrency market data

Fetch current market data for the specified cryptocurrencies. `symbols` is a comma-separated list of CoinGecko IDs (e.g. `bitcoin,ethereum,solana`).

Parameters

Name	In	Type	Required	Description
`symbols`	path	string	Yes	Comma-separated list of cryptocurrency symbols.

Responses

200Array of market data records

application/json

[
  {
    "id": 1,
    "symbol": "BTC",
    "name": "Bitcoin",
    "price": 64321.12,
    "marketCap": 1268000000000,
    "marketCapRank": 1,
    "circulatingSupply": 19712000,
    "totalSupply": 21000000,
    "maxSupply": 21000000,
    "volume24h": 32100000000,
    "volatility": 0.62,
    "communityScore": 87.4,
    "developerScore": 92.1,
    "liquidityScore": 95,
    "publicInterestScore": 88.6,
    "lastUpdated": "2024-09-12T15:04:05Z"
  }
]

429Rate limit exceeded.

500Server error.

QScore

Portfolio risk and credit-style scoring (Q, F, R scores).

POST/api/calculate-portfolio-scoreQScore

Calculate portfolio Q Score

Calculate the overall Q Score, F Score, and R Score for a cryptocurrency portfolio described by per-asset allocation percentages.

Request body

application/json

{
  "btcAllocation": 60,
  "ethAllocation": 30,
  "solAllocation": 10
}

Responses

200Portfolio Q Score result

application/json

{
  "qScore": 82.4,
  "fScore": 78.1,
  "rScore": 64.9,
  "allocation": {
    "BTC": 60,
    "ETH": 30,
    "SOL": 10
  },
  "breakdown": {
    "BTC": 88,
    "ETH": 79,
    "SOL": 65
  }
}

400Missing score data or invalid allocations.

500Server error.

GET/api/scoresQScore

Get all cryptocurrency Q scores

Retrieve Q scores, F scores, and R scores for all tracked cryptocurrencies.

Responses

200Per-asset score table

application/json

[
  {
    "symbol": "BTC",
    "qScore": 88,
    "fScore": 90.1,
    "rScore": 70.2
  },
  {
    "symbol": "ETH",
    "qScore": 79,
    "fScore": 81.5,
    "rScore": 64
  }
]

500Server error.

POST/qscore/evaluateQScore

Evaluate a QScore for a linked account

Compute a QScore for a portfolio snapshot already linked via ByAllAccounts.

Request body

application/json

{
  "account_id": "acct_01HVYX",
  "as_of_date": "2026-04-15"
}

Responses

200QScore result

application/json

{
  "score": 812,
  "grade": "A+",
  "btc_weight": "64%",
  "risk_level": "aggressive"
}

400Malformed request body.

Portfolios

Cryptocurrency portfolio CRUD with weighted allocations.

GET/api/portfoliosPortfolios

Get all portfolios

Retrieve all user portfolios with their allocations.

Responses

200Portfolio list

application/json

[
  {
    "id": "pf_01HVYX",
    "name": "Conservative Crypto",
    "allocations": {
      "BTC": 70,
      "ETH": 30
    }
  }
]

401Unauthorized.

POST/api/portfoliosPortfolios

Create a new portfolio

Create a new cryptocurrency portfolio.

Request body

application/json

{
  "name": "Aggressive Growth",
  "allocations": {
    "BTC": 50,
    "ETH": 30,
    "SOL": 20
  }
}

Responses

201Created

application/json

{
  "id": "pf_01HVZY",
  "name": "Aggressive Growth",
  "allocations": {
    "BTC": 50,
    "ETH": 30,
    "SOL": 20
  }
}

400Allocations must sum to 100.

GET/api/portfolios/{id}Portfolios

Get portfolio by ID

Retrieve a specific portfolio with its allocations.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Portfolio identifier.

Responses

200Portfolio detail

application/json

{
  "id": "pf_01HVYX",
  "name": "Conservative Crypto",
  "allocations": {
    "BTC": 70,
    "ETH": 30
  },
  "qScore": 82.4
}

404Portfolio not found.

PUT/api/portfolios/{id}Portfolios

Update portfolio

Update an existing portfolio (replaces allocations).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Portfolio identifier.

Request body

application/json

{
  "name": "Conservative Crypto v2",
  "allocations": {
    "BTC": 65,
    "ETH": 35
  }
}

Responses

200Updated

application/json

{
  "id": "pf_01HVYX",
  "name": "Conservative Crypto v2",
  "allocations": {
    "BTC": 65,
    "ETH": 35
  }
}

404Portfolio not found.

DELETE/api/portfolios/{id}Portfolios

Delete portfolio

Delete a portfolio and its allocations.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Portfolio identifier.

Responses

204Portfolio deleted.

404Portfolio not found.

Status

Service status and health probes.

GET/api/statusStatus

Get API status and health information

Check API connectivity, rate limits, and system status.

Responses

200Service status

application/json

{
  "status": "ok",
  "uptimeSeconds": 481239,
  "rateLimitRemaining": 1000,
  "version": "2026.04.1"
}

ByAllAccounts

Aggregated financial accounts and portfolio summaries.

GET/portfolio/summaryByAllAccounts

Portfolio summary

Returns an aggregated portfolio summary across linked institutions.

Parameters

Name	In	Type	Required	Description
`account_id`	query	string	No	Restrict the summary to a single linked account.

Responses

200Aggregated portfolio summary

application/json

{
  "btc_balance": "2.847 BTC",
  "usd_value": "$274,318",
  "exchanges": [
    "Coinbase",
    "Kraken"
  ],
  "sync_status": "live"
}

401Missing or invalid bearer token.

TAIP

Cryptoasset tax reporting and Form 8949 generation.

GET/taip/gains-reportTAIP

Gains report

Realized and unrealized gains for an account, ready for Form 8949.

Parameters

Name	In	Type	Required	Description
`tax_year`	query	integer	Yes	Tax year (e.g. 2026).

Responses

200Gains report

application/json

{
  "asset": "BTC",
  "net_gains": "$98,140",
  "transactions": 312,
  "form_8949": "ready"
}

Qeychain

Wallet-address-based holdings, cost basis, IRS Schedule 1.

GET/qeychain/walletsQeychain

List tracked wallets

Returns a paginated list of wallets tracked under your organization.

Parameters

Name	In	Type	Required	Description
`limit`	query	integer	No	Page size (default 50, max 200).
`cursor`	query	string	No	Cursor returned by a previous page.

Responses

200Paginated wallet list

application/json

{
  "data": [
    {
      "address": "bc1qxy2k...",
      "chain": "bitcoin",
      "btc_holdings": "1.204 BTC",
      "cost_basis": "$51,200",
      "unrealized_pnl": "+$64,918"
    }
  ],
  "next_cursor": null
}

Q-Sim

Portfolio simulation and scenario modeling.

POST/qsim/simulateQ-Sim

Run a portfolio simulation

Run scenario projections (bull/base/bear) over a target horizon.

Request body

application/json

{
  "portfolio": [
    {
      "symbol": "BTC",
      "weight": 0.6
    },
    {
      "symbol": "ETH",
      "weight": 0.4
    }
  ],
  "horizon_years": 5,
  "scenarios": [
    "bull",
    "base",
    "bear"
  ]
}

Responses

200Simulation result

application/json

{
  "scenarios": [
    {
      "name": "bull",
      "cagr": "21.4%",
      "terminal_usd": "$264,118"
    },
    {
      "name": "base",
      "cagr": "9.2%",
      "terminal_usd": "$155,402"
    },
    {
      "name": "bear",
      "cagr": "-3.1%",
      "terminal_usd": "$85,431"
    }
  ]
}

ROI

Investment ROI and benchmark projections.

GET/roi/projectionROI

ROI projection

Single-shot ROI projection given a principal and horizon.

Parameters

Name	In	Type	Required	Description
`principal_usd`	query	number	Yes	Principal amount in USD.
`horizon_years`	query	integer	Yes	Investment horizon in years.

Responses

200ROI projection

application/json

{
  "principal_usd": 100000,
  "horizon_years": 10,
  "terminal_usd": "$248,400",
  "cagr": "9.5%",
  "benchmark_diff": "+2.1%"
}