{ "openapi": "3.1.0", "info": { "title": "Turnqey API", "version": "2026.04.1", "summary": "Cryptoasset infrastructure for Registered Investment Advisors.", "description": "Unified API surface across the Turnqey product line - Turnqey API (accounts, transactions, balances, integrity), QScore (market data, scoring, portfolios), TAIP (tax reporting), Q-Sim, ROI Calculator, Qeychain (wallet tracking), and ByAllAccounts aggregation.", "contact": { "name": "Turnqey Developer Support", "email": "support@turnqey.xyz", "url": "https://docs.turnqey.xyz/" } }, "servers": [ { "url": "https://api.turnqey.xyz", "description": "Turnqey API - Production (use /v1/api/* paths)" }, { "url": "https://sandbox.turnqey.xyz", "description": "Sandbox" } ], "tags": [ { "name": "Auth", "description": "Bearer-token issuance for the Turnqey API." }, { "name": "Accounts", "description": "Cryptoasset accounts, identity lookups, transactions, and balances." }, { "name": "Integrity", "description": "Data checksum endpoints used for partner reconciliation." }, { "name": "Cryptoassets", "description": "Market data, prices, and reference info for tracked cryptocurrencies." }, { "name": "QScore", "description": "Portfolio risk and credit-style scoring (Q, F, R scores)." }, { "name": "Portfolios", "description": "Cryptocurrency portfolio CRUD with weighted allocations." }, { "name": "Status", "description": "Service status and health probes." }, { "name": "ByAllAccounts", "description": "Aggregated financial accounts and portfolio summaries." }, { "name": "TAIP", "description": "Cryptoasset tax reporting and Form 8949 generation." }, { "name": "Qeychain", "description": "Wallet-address-based holdings, cost basis, IRS Schedule 1." }, { "name": "Q-Sim", "description": "Portfolio simulation and scenario modeling." }, { "name": "ROI", "description": "Investment ROI and benchmark projections." } ], "security": [ { "Bearer": [] } ], "paths": { "/v1/api/token": { "post": { "operationId": "createToken", "tags": [ "Auth" ], "summary": "Generate authentication token", "description": "Creates a new JWT token using client credentials. Tokens are valid for one hour - call this endpoint hourly to rotate.", "requestBody": { "required": true, "content": { "application/json": { "example": { "clientId": "tnq_client_01HVYX", "clientSecret": "••••••••" } } } }, "responses": { "200": { "description": "Token issued", "content": { "application/json": { "example": { "isError": false, "message": "Success", "result": { "accessToken": "eyJhbGciOiJIUzI1Ni…", "expiresIn": 3600, "tokenType": "Bearer" }, "statusCode": 200 } } } }, "401": { "description": "Invalid client credentials." } }, "security": [] } }, "/v1/api/account/collection/{collectionId}": { "get": { "operationId": "getAccountByCollection", "tags": [ "Accounts" ], "summary": "Get account collection by ID", "description": "Retrieves account information for a specific collection identified by its UUID.", "parameters": [ { "name": "collectionId", "in": "path", "required": true, "description": "UUID of the account collection.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Account collection", "content": { "application/json": { "example": { "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 } } } }, "401": { "description": "Unauthorized - bearer token missing or invalid." }, "404": { "description": "Collection not found." } } } }, "/v1/api/account/identity/{identity}": { "get": { "operationId": "getAccountByIdentity", "tags": [ "Accounts" ], "summary": "Get account by identity", "description": "Retrieves account information for a specific identity string (e.g. external advisor identifier).", "parameters": [ { "name": "identity", "in": "path", "required": true, "description": "Identity string used by the partner system.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account record", "content": { "application/json": { "example": { "isError": false, "message": "Success", "result": { "accountId": "12345678-e89b-12d3-a456-426614174000", "identity": "advisor_42", "platform": "kraken" }, "statusCode": 200 } } } }, "401": { "description": "Unauthorized." }, "404": { "description": "Identity not found." } } } }, "/v1/api/account/{accountId}/transactions": { "get": { "operationId": "getAccountTransactions", "tags": [ "Accounts" ], "summary": "Get account transactions", "description": "Retrieves transaction history for a specific account identified by its UUID.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "description": "UUID of the account.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive start date (ISO-8601).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive end date (ISO-8601).", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Transaction history", "content": { "application/json": { "example": { "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 } } } }, "401": { "description": "Unauthorized." } } } }, "/v1/api/account/{accountId}/balances": { "get": { "operationId": "getAccountBalances", "tags": [ "Accounts" ], "summary": "Get account balances", "description": "Retrieves current balances for a specific account identified by its UUID.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "description": "UUID of the account.", "schema": { "type": "string", "format": "uuid" } }, { "name": "forceRefresh", "in": "query", "required": false, "description": "Force a refresh from the source if cached data is older than 30 minutes.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Account balances", "content": { "application/json": { "example": { "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 } } } }, "401": { "description": "Unauthorized." }, "422": { "description": "Unprocessable entity." } } } }, "/v1/api/checksum": { "get": { "operationId": "getChecksum", "tags": [ "Integrity" ], "summary": "Get data checksum", "description": "Retrieves a checksum for data verification, filtered by platform, collection, or identity.", "parameters": [ { "name": "platform", "in": "query", "required": false, "description": "Filter by source platform (e.g. coinbase, kraken).", "schema": { "type": "string" } }, { "name": "collectionId", "in": "query", "required": false, "description": "Filter by account collection.", "schema": { "type": "string", "format": "uuid" } }, { "name": "identity", "in": "query", "required": false, "description": "Filter by external identity string.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Checksum payload", "content": { "application/json": { "example": { "isError": false, "message": "Success", "result": { "checksum": "f3a1c0b9d4e8…", "computedAt": "2024-09-12T15:04:05Z", "rowCount": 4218 }, "statusCode": 200 } } } }, "401": { "description": "Unauthorized." } } } }, "/api/crypto-data/{symbols}": { "get": { "operationId": "getCryptoData", "tags": [ "Cryptoassets" ], "summary": "Get cryptocurrency market data", "description": "Fetch current market data for the specified cryptocurrencies. `symbols` is a comma-separated list of CoinGecko IDs (e.g. `bitcoin,ethereum,solana`).", "parameters": [ { "name": "symbols", "in": "path", "required": true, "description": "Comma-separated list of cryptocurrency symbols.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of market data records", "content": { "application/json": { "example": [ { "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" } ] } } }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." } } } }, "/api/calculate-portfolio-score": { "post": { "operationId": "calculatePortfolioScore", "tags": [ "QScore" ], "summary": "Calculate portfolio Q Score", "description": "Calculate the overall Q Score, F Score, and R Score for a cryptocurrency portfolio described by per-asset allocation percentages.", "requestBody": { "required": true, "content": { "application/json": { "example": { "btcAllocation": 60, "ethAllocation": 30, "solAllocation": 10 } } } }, "responses": { "200": { "description": "Portfolio Q Score result", "content": { "application/json": { "example": { "qScore": 82.4, "fScore": 78.1, "rScore": 64.9, "allocation": { "BTC": 60, "ETH": 30, "SOL": 10 }, "breakdown": { "BTC": 88, "ETH": 79, "SOL": 65 } } } } }, "400": { "description": "Missing score data or invalid allocations." }, "500": { "description": "Server error." } } } }, "/api/scores": { "get": { "operationId": "getScores", "tags": [ "QScore" ], "summary": "Get all cryptocurrency Q scores", "description": "Retrieve Q scores, F scores, and R scores for all tracked cryptocurrencies.", "responses": { "200": { "description": "Per-asset score table", "content": { "application/json": { "example": [ { "symbol": "BTC", "qScore": 88, "fScore": 90.1, "rScore": 70.2 }, { "symbol": "ETH", "qScore": 79, "fScore": 81.5, "rScore": 64 } ] } } }, "500": { "description": "Server error." } } } }, "/api/status": { "get": { "operationId": "getStatus", "tags": [ "Status" ], "summary": "Get API status and health information", "description": "Check API connectivity, rate limits, and system status.", "responses": { "200": { "description": "Service status", "content": { "application/json": { "example": { "status": "ok", "uptimeSeconds": 481239, "rateLimitRemaining": 1000, "version": "2026.04.1" } } } } } } }, "/api/portfolios": { "get": { "operationId": "listPortfolios", "tags": [ "Portfolios" ], "summary": "Get all portfolios", "description": "Retrieve all user portfolios with their allocations.", "responses": { "200": { "description": "Portfolio list", "content": { "application/json": { "example": [ { "id": "pf_01HVYX", "name": "Conservative Crypto", "allocations": { "BTC": 70, "ETH": 30 } } ] } } }, "401": { "description": "Unauthorized." } } }, "post": { "operationId": "createPortfolio", "tags": [ "Portfolios" ], "summary": "Create a new portfolio", "description": "Create a new cryptocurrency portfolio.", "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Aggressive Growth", "allocations": { "BTC": 50, "ETH": 30, "SOL": 20 } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "id": "pf_01HVZY", "name": "Aggressive Growth", "allocations": { "BTC": 50, "ETH": 30, "SOL": 20 } } } } }, "400": { "description": "Allocations must sum to 100." } } } }, "/api/portfolios/{id}": { "get": { "operationId": "getPortfolio", "tags": [ "Portfolios" ], "summary": "Get portfolio by ID", "description": "Retrieve a specific portfolio with its allocations.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Portfolio identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Portfolio detail", "content": { "application/json": { "example": { "id": "pf_01HVYX", "name": "Conservative Crypto", "allocations": { "BTC": 70, "ETH": 30 }, "qScore": 82.4 } } } }, "404": { "description": "Portfolio not found." } } }, "put": { "operationId": "updatePortfolio", "tags": [ "Portfolios" ], "summary": "Update portfolio", "description": "Update an existing portfolio (replaces allocations).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Portfolio identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Conservative Crypto v2", "allocations": { "BTC": 65, "ETH": 35 } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "example": { "id": "pf_01HVYX", "name": "Conservative Crypto v2", "allocations": { "BTC": 65, "ETH": 35 } } } } }, "404": { "description": "Portfolio not found." } } }, "delete": { "operationId": "deletePortfolio", "tags": [ "Portfolios" ], "summary": "Delete portfolio", "description": "Delete a portfolio and its allocations.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Portfolio identifier.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Portfolio deleted." }, "404": { "description": "Portfolio not found." } } } }, "/portfolio/summary": { "get": { "operationId": "getPortfolioSummary", "tags": [ "ByAllAccounts" ], "summary": "Portfolio summary", "description": "Returns an aggregated portfolio summary across linked institutions.", "parameters": [ { "name": "account_id", "in": "query", "required": false, "description": "Restrict the summary to a single linked account.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Aggregated portfolio summary", "content": { "application/json": { "example": { "btc_balance": "2.847 BTC", "usd_value": "$274,318", "exchanges": [ "Coinbase", "Kraken" ], "sync_status": "live" } } } }, "401": { "description": "Missing or invalid bearer token." } } } }, "/qscore/evaluate": { "post": { "operationId": "evaluateQScore", "tags": [ "QScore" ], "summary": "Evaluate a QScore for a linked account", "description": "Compute a QScore for a portfolio snapshot already linked via ByAllAccounts.", "requestBody": { "required": true, "content": { "application/json": { "example": { "account_id": "acct_01HVYX", "as_of_date": "2026-04-15" } } } }, "responses": { "200": { "description": "QScore result", "content": { "application/json": { "example": { "score": 812, "grade": "A+", "btc_weight": "64%", "risk_level": "aggressive" } } } }, "400": { "description": "Malformed request body." } } } }, "/taip/gains-report": { "get": { "operationId": "getGainsReport", "tags": [ "TAIP" ], "summary": "Gains report", "description": "Realized and unrealized gains for an account, ready for Form 8949.", "parameters": [ { "name": "tax_year", "in": "query", "required": true, "description": "Tax year (e.g. 2026).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Gains report", "content": { "application/json": { "example": { "asset": "BTC", "net_gains": "$98,140", "transactions": 312, "form_8949": "ready" } } } } } } }, "/qeychain/wallets": { "get": { "operationId": "listWallets", "tags": [ "Qeychain" ], "summary": "List tracked wallets", "description": "Returns a paginated list of wallets tracked under your organization.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (default 50, max 200).", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor returned by a previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated wallet list", "content": { "application/json": { "example": { "data": [ { "address": "bc1qxy2k...", "chain": "bitcoin", "btc_holdings": "1.204 BTC", "cost_basis": "$51,200", "unrealized_pnl": "+$64,918" } ], "next_cursor": null } } } } } } }, "/qsim/simulate": { "post": { "operationId": "runSimulation", "tags": [ "Q-Sim" ], "summary": "Run a portfolio simulation", "description": "Run scenario projections (bull/base/bear) over a target horizon.", "requestBody": { "required": true, "content": { "application/json": { "example": { "portfolio": [ { "symbol": "BTC", "weight": 0.6 }, { "symbol": "ETH", "weight": 0.4 } ], "horizon_years": 5, "scenarios": [ "bull", "base", "bear" ] } } } }, "responses": { "200": { "description": "Simulation result", "content": { "application/json": { "example": { "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/projection": { "get": { "operationId": "getRoiProjection", "tags": [ "ROI" ], "summary": "ROI projection", "description": "Single-shot ROI projection given a principal and horizon.", "parameters": [ { "name": "principal_usd", "in": "query", "required": true, "description": "Principal amount in USD.", "schema": { "type": "number" } }, { "name": "horizon_years", "in": "query", "required": true, "description": "Investment horizon in years.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "ROI projection", "content": { "application/json": { "example": { "principal_usd": 100000, "horizon_years": 10, "terminal_usd": "$248,400", "cagr": "9.5%", "benchmark_diff": "+2.1%" } } } } } } } }, "components": { "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT bearer token issued by POST /v1/api/token." } } } }