# On-Demand Crypto Data via x402 Source: https://coinstats.app/docs/ai-agents/x402 Pay-per-request access to CoinStats market data, wallet balances, news, and portfolio reads — no API key required. Built on Coinbase's x402 open payment protocol. These endpoints are pay-per-use and intended for AI agents and experimental use cases. Features and pricing may change. For production workloads, we recommend the standard [API key authentication](/docs/authentication) flow. ## x402 Overview [x402](https://www.x402.org) is an open payment protocol developed by Coinbase that uses HTTP `402 Payment Required` responses to charge for individual API calls with instant stablecoin payments. Instead of signing up for an account and managing an API key, agents pay in USDC per request directly from a wallet. CoinStats exposes a pay-per-use surface covering every read-only endpoint in the CoinStats Public API — live coin prices, market data, news, insights, wallet balances and DeFi positions, plus shared portfolio reads. ## How It Works Every request to a protected endpoint follows the same three-step flow: Send a normal `GET` request. Because no payment is attached, the gateway responds with HTTP `402 Payment Required` — the response includes the required amount, currency, wallet address, and network. Your wallet signs an EIP-3009 `transferWithAuthorization` for the exact amount. The [`@x402/fetch`](https://www.npmjs.com/package/@x402/fetch) client library handles this automatically; custom clients can sign with any EIP-712-compatible wallet. Send the same request again, this time with the `X-PAYMENT` header containing the signed authorization. The facilitator settles on chain and the gateway returns the data with an `X-PAYMENT-RESPONSE` receipt. A `Set-Cookie: auth_token=...` header is also issued — subsequent calls within one hour skip the facilitator entirely. ## Authentication No API key is needed. Point your client at the dedicated x402 subdomain and skip the `x-api-key` header: ```text theme={null} https://x402.coinstats.app ``` Every path that exists at `https://api.coinstats.app/v1` under the supported list below is gated by x402 at `https://x402.coinstats.app`. ## Supported Endpoints Every listed endpoint is a read-only `GET`. Prices are quoted in USDC and settle on Base mainnet (chain ID 8453). | Endpoint | Price | Description | | -------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `GET /coins` | \$0.001 | CoinStats list of all cryptocurrencies with live market data — price, volume, market cap, rank, % changes | | `GET /wallet/defi` | \$0.04 | CoinStats DeFi positions for a wallet — staked, lent, borrowed, LP balances across protocols (Aave, Lido, Uniswap, Curve, etc.) | | `GET /coins/{coinId}` | \$0.001 | CoinStats detailed data for a single cryptocurrency — price, market cap, supply, rank, links | | `GET /wallet/balance` | \$0.004 | CoinStats live balance for a wallet address on a single blockchain — coins and token amounts with USD values | | `GET /coins/price/avg` | \$0.001 | CoinStats historical average price for a cryptocurrency at a given timestamp | | `GET /coins/price/exchange` | \$0.001 | CoinStats historical price on a specific exchange (Binance, Coinbase, Kraken, etc.) at a timestamp | | `GET /coins/{coinId}/charts` | \$0.001 | CoinStats price chart for a single cryptocurrency — time series over 24h/1w/1m/1y/all | | `GET /markets` | \$0.001 | CoinStats global cryptocurrency market data — total market cap, 24h volume, BTC dominance, % changes | | `GET /tickers/exchanges` | \$0.001 | CoinStats list of supported cryptocurrency exchanges with metadata | | `GET /tickers/markets` | \$0.001 | CoinStats ticker market data — live prices across exchanges for a trading pair | | `GET /fiats` | \$0.001 | CoinStats list of supported fiat currencies (USD, EUR, GBP, JPY, etc.) with conversion metadata | | `GET /currencies` | \$0.001 | CoinStats live currency exchange rates for supported fiat pairs | | `GET /news/sources` | \$0.001 | CoinStats list of crypto news sources aggregated across the industry | | `GET /news/type/{type}` | \$0.001 | CoinStats crypto news filtered by topic (handpicked, trending, latest, bullish, bearish) | | `GET /news/{id}` | \$0.001 | CoinStats crypto news article by id — title, body, source, sentiment | | `GET /news` | \$0.001 | CoinStats latest crypto news feed — articles on Bitcoin, Ethereum, DeFi, NFTs, regulation | | `GET /insights/btc-dominance` | \$0.001 | CoinStats Bitcoin market dominance percentage over time — share of total crypto market cap | | `GET /insights/fear-and-greed/chart` | \$0.001 | CoinStats Fear & Greed Index historical chart — market sentiment over time | | `GET /insights/fear-and-greed` | \$0.001 | CoinStats current Fear & Greed Index — sentiment score from Extreme Fear (0) to Extreme Greed (100) | | `GET /insights/rainbow-chart/{coinId}` | \$0.001 | CoinStats rainbow chart for BTC/ETH — logarithmic valuation bands from cycle lows to bubble highs | | `GET /wallet/blockchains` | \$0.001 | CoinStats list of supported wallet blockchains and their connectionId identifiers | | `GET /wallet/balance/many` | \$0.004 | CoinStats multi-chain wallet balances — aggregate holdings across multiple wallets + blockchains in one call | | `GET /wallet/status` | \$0.001 | CoinStats wallet sync status — whether CoinStats has finished indexing transactions for the given wallet | | `GET /wallet/transactions` | \$0.003 | CoinStats wallet transaction history — token transfers, swaps, buys, sells for a wallet address | | `GET /wallet/charts` | \$0.004 | CoinStats portfolio value charts across multiple wallets — aggregated historical balance over time | | `GET /wallet/chart` | \$0.004 | CoinStats portfolio value chart for a single wallet — historical USD value with PnL | | `GET /exchange/support` | \$0.001 | CoinStats list of supported cryptocurrency exchanges for portfolio connection (Binance, Coinbase, Kraken, Bybit, OKX, etc.) | | `GET /portfolio/snapshot/items` | \$0.05 | CoinStats portfolio snapshot — historical coin balances over time for a shared portfolio. Requires sharetoken header | | `GET /portfolio/value` | \$0.001 | CoinStats shared portfolio total value and PnL — total value, DeFi value, unrealized + realized profit/loss. Requires sharetoken header | | `GET /portfolio/coins` | \$0.001 | CoinStats shared portfolio holdings — all coins with current value, PnL, performance metrics. Requires sharetoken header | | `GET /portfolio/chart` | \$0.001 | CoinStats shared portfolio value chart — historical USD value over 24h/1w/1m/1y. Requires sharetoken header | | `GET /portfolio/transactions` | \$0.001 | CoinStats shared portfolio transaction history — all buys, sells, transfers with timestamps and prices. Requires sharetoken header | | `GET /portfolio/defi` | \$0.04 | CoinStats shared portfolio DeFi positions — staking, lending, LP pools, yield farming across protocols. Requires sharetoken header | Endpoints marked with `sharetoken` require a `sharetoken` header — the CoinStats user shares a portfolio link from the mobile app and hands the token to the agent. See [shareToken](/docs/sharetoken) for how to obtain one. ## Pricing & Payment Method | | | | ---------------- | ------------------------------------------------------------ | | **Network** | Base mainnet (chain ID 8453) | | **Token** | USDC — `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | | **Facilitator** | [Coinbase CDP](https://docs.cdp.coinbase.com/x402) | | **Minimum call** | \$0.001 USDC | | **Gas** | Sponsored by the facilitator — payers need USDC only, no ETH | Pricing is tiered by the underlying data cost. Simple lookups (coin price, markets, news) are $0.001. Wallet-scoped queries are $0.004. Heavy DeFi/portfolio aggregations are $0.04–$0.05. ## Request Example ### Node.js — `@x402/fetch` ```ts theme={null} import { privateKeyToAccount } from "viem/accounts"; import { wrapFetchWithPayment } from "@x402/fetch"; import { registerExactEvmScheme } from "@x402/evm/exact/client"; import { x402Client } from "@x402/core/client"; const account = privateKeyToAccount("0x..."); // wallet funded with USDC on Base const client = new x402Client(); registerExactEvmScheme(client, { signer: account, networks: ["eip155:8453"], }); const paid = wrapFetchWithPayment(fetch, client); const res = await paid("https://x402.coinstats.app/coins/bitcoin"); const data = await res.json(); console.log(data); ``` The first request triggers the 402 → sign → settle loop; subsequent calls within an hour reuse the `auth_token` cookie and skip the facilitator round-trip. ### cURL — manual The `402` challenge is returned in the `payment-required` response header (base64-encoded JSON). To settle manually you'd need to sign an EIP-3009 authorization and replay the request with `X-PAYMENT`. For any real workload, use the `@x402/fetch` client library above. ```bash theme={null} # Probe the challenge — no payment yet curl -s -D - https://x402.coinstats.app/coins/bitcoin -o /dev/null | \ grep -i payment-required | \ sed 's/^payment-required: //' | base64 -d | jq ``` ## Response Example ```json theme={null} { "id": "bitcoin", "icon": "https://static.coinstats.app/coins/1650455588819.png", "name": "Bitcoin", "symbol": "BTC", "rank": 1, "price": 43250.75, "priceBtc": 1, "volume": 15420000000, "marketCap": 849231200000, "availableSupply": 19628543, "totalSupply": 21000000, "priceChange1h": 0.12, "priceChange1d": 2.45, "priceChange1w": -1.87, "priceChange1m": 5.24 } ``` The `X-PAYMENT-RESPONSE` header on a 200 contains the settlement receipt (transaction hash + facilitator ack) for record-keeping. ## Discovery CoinStats endpoints are discoverable by agents via two indexes: * **[CDP Bazaar](https://docs.cdp.coinbase.com/x402/bazaar)** — every paid call is indexed under `https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources` with full-text searchable descriptions and input/output schemas. * **[agentic.market](https://agentic.market)** — surfaces CoinStats in its AI-agent marketplace alongside other x402-enabled data services. ## Further Reading * [x402 protocol site](https://www.x402.org) — spec, reference clients, ecosystem * [CDP x402 Quickstart](https://docs.cdp.coinbase.com/x402/quickstart) * [Cloudflare's x402 integration post](https://blog.cloudflare.com/x402/) * [CoinStats Public API reference](/docs/api-reference) — detailed schemas for every endpoint # API Reference Source: https://coinstats.app/docs/api-reference/introduction Every CoinStats API endpoint, grouped by what it does. Base URL, authentication, and where to find each section. Every endpoint lives under a single base URL and one API key. Pick a section below, or expand a folder in the sidebar to browse endpoints directly. ```bash theme={null} curl "https://api.coinstats.app/v1/coins?limit=5" \ -H "X-API-KEY: YOUR_API_KEY" ``` Every request needs an `X-API-KEY` header — see [Authentication](/docs/authentication) to generate one. Responses are JSON. Errors follow a shared shape documented in [Error Codes](/docs/errors). ## Sections Coin prices, charts, tickers, exchange rates, and fiat currencies. Plus market insights, news, NFT collections, and token risk scores. Balances, transactions, P/L, and DeFi positions for any address across 120+ chains. Exchange connections and user portfolio analytics. Polymarket markets, events, order books, price history, and trader analytics. Your remaining credits and the current API status. ## Before you start Generate a key and send it on every request. Per-plan request ceilings and what a `429` means. How much each endpoint costs against your quota. Building an AI agent? The [MCP server](/docs/mcp/connecting) exposes this same data as tools, and [x402](/docs/ai-agents/x402) lets you pay per request with no account at all. # Authentication Source: https://coinstats.app/docs/authentication Learn how to authenticate with the CoinStats API Building an AI agent and want to skip the sign-up? See [x402 Pay-Per-Request](/docs/ai-agents/x402) — no account, no API key, just a Base wallet with USDC. The CoinStats API uses API key authentication for all requests. Follow these steps to get started: Visit the [CoinStats API dashboard](https://openapi.coinstats.app) and create an account or log in to your existing one. After signing in, go to your dashboard and generate a new API key. This key will be used to authenticate your requests. Add the API key to the `X-API-KEY` header in every request you make. ```bash theme={null} curl -H "X-API-KEY: your-api-key" \ https://api.coinstats.app/v1/coins ``` ```javascript theme={null} const response = await fetch('https://api.coinstats.app/v1/coins', { headers: { 'X-API-KEY': 'your-api-key' } }); const data = await response.json(); ``` **API Key Security Alert**: Exposed API keys can lead to unauthorized usage, quota exhaustion, and unexpected charges. Always protect your keys in production applications. ## Why Key Protection Matters When you expose API keys on the client side, malicious actors can discover and abuse them, potentially: Malicious usage can quickly consume your API limits and cause service interruptions Unauthorized requests can push you over plan limits and trigger unexpected charges ## Essential Security Practices Never hardcode API keys in your source code. Use environment variables instead. ```javascript theme={null} // ❌ Don't do this const apiKey = "your-api-key-here"; // ✅ Do this instead const apiKey = process.env.COINSTATS_API_KEY; ``` ```bash theme={null} # .env file COINSTATS_API_KEY=your-actual-api-key ``` **Never expose API keys in frontend code.** Use these approaches instead: Create a backend endpoint that forwards requests to CoinStats: ```javascript theme={null} // Backend endpoint app.get('/api/coins', async (req, res) => { const response = await fetch('https://api.coinstats.app/v1/coins', { headers: { 'X-API-KEY': process.env.COINSTATS_API_KEY } }); const data = await response.json(); res.json(data); }); // Frontend code (no API key needed) const response = await fetch('/api/coins'); const data = await response.json(); ``` Fetch data server-side and pass it to your frontend: ```javascript theme={null} // Next.js example export async function getServerSideProps() { const response = await fetch('https://api.coinstats.app/v1/coins', { headers: { 'X-API-KEY': process.env.COINSTATS_API_KEY } }); const data = await response.json(); return { props: { coins: data } }; } ``` Use different API keys for development, staging, and production: ```javascript theme={null} const getApiKey = () => { switch (process.env.NODE_ENV) { case 'production': return process.env.COINSTATS_API_KEY_PROD; case 'staging': return process.env.COINSTATS_API_KEY_STAGING; default: return process.env.COINSTATS_API_KEY_DEV; } }; ``` Create a new API key in your CoinStats dashboard Update all applications to use the new key Ensure all services work with the new key Delete the old key from your dashboard ## Security Checklist * [ ] Use environment variables for API keys * [ ] Never commit API keys to version control * [ ] Add `.env` to `.gitignore` * [ ] Use different keys for different environments * [ ] Keep API keys server-side only * [ ] Monitor API usage regularly in dashboard * [ ] Set up usage alerts * [ ] Rotate keys regularly * [ ] Document security procedures for your team **Monitor Usage**: Regularly check your API usage in the CoinStats dashboard for unusual patterns like sudden spikes, requests from unexpected locations, or usage during off-hours. If your API key is missing or incorrect, you'll receive a `401 Unauthorized` response: ```json theme={null} { "error": "Unauthorized", "message": "Invalid API key" } ``` # Changelog Source: https://coinstats.app/docs/changelog Product updates and announcements **Historical profit and loss endpoints** * **GET /wallet/pl/history** — Cash-flow-adjusted history for one wallet across one or more requested networks. * **GET /exchange/pl/history** — Cash-flow-adjusted history for an owned exchange portfolio. * **GET /portfolio/pl/history** — Cash-flow-adjusted history for one API-connected portfolio, all owned portfolios, or a shared portfolio. * Each endpoint costs **25 credits** per request. Wallet network multipliers still apply. * Request a rolling preset such as `range=1m`, or provide `from` and `to` for a specific historical period. See the [wallet P\&L history API reference](/docs/openapi/get-wallet-pl-history) for a calendar-month example. **All-time high/low added to coin response** * Coin responses now include `allTimeHigh` and `allTimeLow`, returned in the requested `currency`. * Fields are optional and only present for coins that have the data. **Prediction Markets API (Polymarket + Kalshi)** * New read-only **Prediction Markets** section under `GET /prediction/*` — analytics for Polymarket and Kalshi across markets, events, traders, platform analytics, search, and tags. See the [overview](/docs/prediction/overview). * **Markets & events** — list/trending/detail, current prices, Yes-price history, and **cross-venue matching** (`/prediction/markets/{slug}/cross-venue`, `/prediction/events/{slug}/cross-venue`, **10 credits**) that pairs the same question across both venues with a confidence score and price delta. * **Traders** — leaderboard, profile, open positions, trade history, PnL breakdown, category stats, score, and more (2–3 credits). * **Analytics, search & tags** — platform overview, composite market signals, cross-entity search, and the tag list. * Prices are probabilities in `0..1`, money is USD, dates are ISO 8601. Every endpoint uses `X-API-KEY` auth and returns the standard `{ success, data, meta?, timestamp }` envelope. **Free plan limits updated** * Free plan credits reduced from 50,000 to **20,000** credits/month. * Free plan rate limit reduced from 5 req/sec to **2 req/sec**. **Token Risks endpoint** * New: **GET /token-risks** — 5000 credits. Smart-contract risk analysis powered by Hexens: overall risk score plus detailed findings (centralized mint/burn, blacklist/whitelist, pausable/blockable transfers, hidden fees, upgradeable proxy, ownership not renounced, balance manipulation, and more). * Accepts either `coinId` (CoinStats coin id) or an explicit `contractAddress` + `chain` pair. Optional `sortBy=severity`. * Returns an empty `results` list when no risk data is available (non-EVM tokens or contracts not yet indexed). **ConnectKit launched** * Added [ConnectKit](/docs/connectkit), a hosted CoinStats popup flow for connecting wallets and exchanges from partner apps. * Added ConnectKit setup in the [API dashboard](https://openapi.coinstats.app/connect-kits) with trusted origins, redirect URLs, branding, mode, appearance, and accent color controls. * Added browser integrations through `@coinstats/connectkit` and the hosted `https://connect.coinstats.app/coinstats-connect.js` script. * Frontend apps use only the public ConnectKit ID and callback URL. API keys stay server-side. **Flare EVM chain support** * Added support for the MegaETH EVM chain across wallet endpoints. **Wallet multi-balance endpoint renamed** * New: **GET /wallet/balance/many** — same credits and response shape as the previous `/wallet/balances`. * **GET /wallet/balances** is deprecated and removed from the API reference. It continues to work and now returns `Deprecation: true` and a `Link` header pointing to `/wallet/balance/many`. Migrate when convenient. **Sei EVM chain support** * Added support for the Sei EVM chain across wallet endpoints. * Includes balances. **MegaETH EVM chain support** * Added support for the MegaETH EVM chain across wallet endpoints. * Includes balances, DeFi positions, and transaction history. **PnL endpoints added for connected wallets and exchanges** * **GET /wallet/pl** — 25 credits * **GET /exchange/pl** — 25 credits * Returns holdings with PnL fields, `totalCost`, and summary totals. **Wallet Transactions — credit cost reduced from 40 to 30 per request** * **GET /wallet/transactions** — 30 credits (was 40) * API reference, wallet guides, multiplier docs, and x402 pricing now reflect the updated cost. **Market Insights — credit cost reduced from 50 to 10 per request** * **GET /insights/btc-dominance** — 10 credits (was 50) * **GET /insights/fear-and-greed** — 10 credits (was 50) * **GET /insights/fear-and-greed/chart** — 10 credits (was 50) * **GET /insights/rainbow-chart/\{coinId}** — 10 credits (was 50) **GET /portfolio/list** — 5 credits * New endpoint to retrieve all API-connected portfolios. * Returns `portfolioId` and `portfolioName` for each portfolio created via `POST /portfolio/wallet` or `POST /portfolio/exchange`. **Plan Updates** * Introduced the new **Starter** plan: 1,000,000 credits/month, 30 req/sec, \$49/month. * Free plan credits reduced from 1,000,000 to **50,000** credits/month. * Renamed **Individual** plan to **Pro**. * Renamed **Custom** plan to **Enterprise**. **POST /portfolio/wallet** — Connect a wallet to your CoinStats account * Connect any supported blockchain wallet address to your account. * Returns a `portfolioId` you can use on all `/portfolio` GET endpoints. **POST /portfolio/exchange** — Connect an exchange and create a tracked portfolio * Connect an exchange to your CoinStats account * Returns a `portfolioId` you can use on all `/portfolio` GET endpoints. **GET /portfolio/\*** — `portfolioId` now accepted * All portfolio GET endpoints (`/value`, `/coins`, `/chart`, `/transactions`, `/defi`, `/snapshot/items`) now accept a `portfolioId` query parameter. * `portfolioId` is returned from `POST /portfolio/wallet` or `POST /portfolio/exchange`. * `shareToken` remains fully supported and is unchanged. * If neither is provided, endpoints return aggregated data for all API-connected portfolios. **GET /portfolio/transactions** - Now supports `note` in response **GET /usage/credits** — 0 credits * New endpoint to check your remaining credit limit programmatically. * Returns total credits, used credits, remaining credits, and subscription plan. * This endpoint is free and does not consume any credits. * **GET /wallet/balance** - Now accepts either `connectionId` or `blockchain` parameter * **GET /wallet/balances** - Added `blockchain` parameter (comma-separated list) * **GET /wallet/chart** - Now accepts either `connectionId` or `blockchain` parameter * **GET /wallet/defi** - Now accepts either `connectionId` or `blockchain` parameter * **GET /wallet/transactions** - Now accepts either `connectionId` or `blockchain` parameter * **PATCH /wallet/transactions** - Now accepts either `connectionId` or `blockchain` parameter * If both `connectionId` and `blockchain` are provided, `connectionId` takes precedence **GET /wallet/transactions** * Added `coinId` query param to filter transactions by coin. **GET /wallet/transactions** * Now supports `toAddress` adn `fromAddress` optional properties in the response **GET /coins** * Now supports retrieving Ordinals by specifying the `bitcoin` blockchain in the query. **GET /wallet/defi** * You can now specify multiple `connectionIds` in the query to fetch DeFi data for several connections at once. * Enhanced all existing endpoints for better performance and reliability. * Added comprehensive examples and detailed descriptions to all endpoints. * Introduced the [Share Token explanation page](/docs/sharetoken) for better understanding. * Launched the [Credit Multipliers page](/docs/multipliers) to explain credit usage. **GET /wallet/balances** * Added `wallets` query parameter to support multiple wallet addresses in a single request * Added `connectionId` field to response when using the `wallets` query parameter **GET /coins** * Added `coinIds` query parameter to filter coins by specific IDs **GET /coins** * Added a new `contractAddresses` field in coin data. * Lists smart contract addresses for tokens (e.g., ERC-20). * Empty for native coins like Bitcoin. **GET /coins/** * Added a new `contractAddresses` field in coin data. * Lists smart contract addresses for tokens (e.g., ERC-20). * Empty for native coins like Bitcoin. **GET /portfolio/value** — 10 credits **GET /portfolio/defi** — 200 credits **GET /wallet/transactions** * Added a new `wallets` query parameter. * This update allows users to retrieve transaction history for multiple wallets in a single API call. **GET /insights/btc-dominance** — 50 credits **GET /insights/fear-and-greed** — 50 credits **GET /insights/fear-and-greed/chart** — 50 credits **GET /insights/rainbow-chart/** — 50 credits **GET /wallet/charts** * Allows users to retrieve chart data for multiple chains and wallets in a single request. **PATCH /wallet/transactions** * Now supports syncing multiple chains and wallets with a single API call. # ConnectKit Tutorial Source: https://coinstats.app/docs/connectkit Create a ConnectKit flow and open the hosted CoinStats connection popup from your app. ConnectKit hosted popup example ConnectKit lets your app send users into a branded CoinStats-hosted popup to connect wallets or exchanges. Your API key stays on CoinStats servers. Your frontend only uses the public ConnectKit ID, redirect URL, and your own `state` value. ## What value this gives * Add wallet and exchange connection to your product without building exchange credential forms yourself. * Keep API keys out of browser code. The ConnectKit ID is public; the API key remains server-side. * Receive a `portfolioId`, `connectionId`, and your original `state` when the connection finishes. * Control which domains can open ConnectKit with allowed origins and redirect URLs. ## Example values Use values like these while testing the flow: | Field | Example value | Where it is used | | -------------- | -------------------------------------------- | ---------------------------------------------------- | | Name | `Example App Portfolio` | Internal dashboard name | | Company name | `Example App` | Displayed inside the hosted popup | | Allowed origin | `https://app.example.com` | The browser origin allowed to open ConnectKit | | Redirect URL | `https://app.example.com/coinstats/callback` | Where CoinStats sends the user after connection | | ConnectKit ID | `pcw_3d349bd92f0c99a219` | Public ID used by your frontend | | State | `user_12345` | Your user/session reference returned with the result | ## Set up ConnectKit Go to the [API dashboard](https://openapi.coinstats.app/connect-kits), open **ConnectKit**, and click **Add**. Fill in the fields that define where ConnectKit can run and how it appears to users: * **Company logo**: Upload the logo shown in the hosted connection popup. * **Name**: Add an internal name for this setup, such as `test` or `prod_app`. * **Company name**: Add the app or brand name users will see, such as `Example App`. * **Allowed origins**: Add every browser origin allowed to open ConnectKit. * **Redirect URLs**: Add the exact callback URLs CoinStats can return to after connection, one per environment. * **Config**: Choose the default mode, appearance, and accent color if you want defaults different from the SDK call. Create ConnectKit form screenshot After saving, copy the ID from the list. This ID is safe to use in browser code. ConnectKit list screenshot Use the npm package or hosted script to open the popup from your app. The popup runs on `connect.coinstats.app`. ## NPM integration Install the SDK: ```bash theme={null} npm install @coinstats/connectkit ``` Open the popup from browser code: ```ts theme={null} import { openCoinStatsConnect } from '@coinstats/connectkit'; openCoinStatsConnect({ id: 'pcw_3d349bd92f0c99a219', redirectUri: 'https://app.example.com/coinstats/callback', state: 'user_12345', mode: 'both', appearance: 'light', accentColor: '#F7931A', onSuccess(result) { console.log('Connected portfolio', result.portfolioId); }, onError(error) { console.error(error.message); }, onClose() { console.log('User closed the popup'); }, }); ``` ## Script tag integration For plain HTML pages, load the hosted browser bundle: ```html theme={null} ``` ## Handle the result When the user finishes, match the returned `state` with the user or session that started the flow. Store the returned `portfolioId` or `connectionId` on your side. Example redirect: ```http theme={null} GET /coinstats/callback ?status=success &portfolioId=portfolio_abc123 &connectionId=binance &state=user_12345 ``` Example popup callback result: ```json theme={null} { "status": "success", "portfolioId": "portfolio_abc123", "connectionId": "binance", "state": "user_12345" } ``` ## Before going live * Add every production origin that can open the popup. * Use HTTPS redirect URLs in production. * Generate and keep the API key in the CoinStats API dashboard. * Store the returned portfolio or connection ID with your user. * Keep API keys server-side. The frontend only needs the ConnectKit ID. # Errors Source: https://coinstats.app/docs/errors Common error responses and troubleshooting # Error Responses The CoinStats API uses standard HTTP status codes to indicate the success or failure of requests. ## HTTP Status Codes | Status Code | Description | | ----------- | ----------------------------------------------------------------- | | `200` | Success - Request completed successfully | | `400` | Bad Request - Invalid parameters or request format | | `401` | Unauthorized - Invalid or missing API key | | `403` | Forbidden - API key lacks permission for this endpoint or plan | | `404` | Not Found - Resource not found | | `409` | Conflict - Resource conflict (e.g., transactions not synced) | | `429` | Too Many Requests - Rate limit or credit limit exceeded | | `503` | Service Unavailable - Upstream dependency temporarily unavailable | | `500` | Internal Server Error - Server error | All error responses share the following shape: ```json theme={null} { "statusCode": 400, "message": "Invalid parameter: coinId", "requestId": "11111111-2222-3333-4444-555555555555", "path": "/coins/invalid-coin" } ``` The `requestId` is a unique identifier for the request — include it when contacting support. ## Common Error Responses ### 400 Bad Request Invalid parameters: ```json theme={null} { "statusCode": 400, "message": "Invalid parameter: coinId", "requestId": "11111111-2222-3333-4444-555555555555", "path": "/coins/invalid-coin" } ``` ### 401 Unauthorized Invalid or missing API key: ```json theme={null} { "statusCode": 401, "message": "Invalid API key", "requestId": "11111111-2222-3333-4444-555555555555", "path": "/coins" } ``` ### 403 Forbidden API key does not have permission for this endpoint (e.g., plan-restricted endpoint): ```json theme={null} { "statusCode": 403, "message": "Forbidden resource", "requestId": "11111111-2222-3333-4444-555555555555", "path": "/wallet/defi/v2" } ``` ### 404 Not Found Resource not found: ```json theme={null} { "statusCode": 404, "message": "Coin with id 'invalid-coin' not found", "requestId": "11111111-2222-3333-4444-555555555555", "path": "/coins/invalid-coin" } ``` ### 409 Conflict Transactions not synced: ```json theme={null} { "statusCode": 409, "message": "Transactions not synced. Please call PATCH /transactions", "requestId": "11111111-2222-3333-4444-555555555555", "path": "/portfolio/transactions" } ``` ### 429 Too Many Requests Rate limit or credit limit exceeded: ```json theme={null} { "statusCode": 429, "message": "Insufficient credits for this request", "requestId": "11111111-2222-3333-4444-555555555555", "path": "/coins" } ``` ### 503 Service Unavailable Upstream service temporarily unavailable (credits charged for the request are automatically refunded): ```json theme={null} { "statusCode": 503, "message": "Service temporarily unavailable", "requestId": "11111111-2222-3333-4444-555555555555", "path": "/wallet/balance" } ``` ## Troubleshooting ### Authentication Issues 1. **Check your API key**: Ensure you're using the correct API key 2. **Verify header format**: Make sure the `X-API-KEY` header is properly set 3. **Check key permissions**: Ensure your API key has the necessary permissions ### Rate Limiting 1. **Monitor credit usage**: Check your credit consumption in the dashboard 2. **Optimize requests**: Use filters and pagination to reduce data transfer 3. **Upgrade plan**: Consider upgrading if you consistently hit limits ### Data Not Found 1. **Verify parameters**: Check that all required parameters are provided 2. **Check data availability**: Some data might not be available for all coins/time periods 3. **Use correct IDs**: Ensure you're using the correct coin IDs from the API ### Wallet/Transaction Issues 1. **Sync transactions**: Call the sync endpoint before requesting transaction data 2. **Check wallet address**: Ensure the wallet address is valid and supported 3. **Verify blockchain**: Make sure the blockchain is supported by CoinStats # CoinStats Crypto API Source: https://coinstats.app/docs/index Best free crypto API for prices, wallet data, and DeFi. 120+ blockchains, 200+ exchanges, 10,000+ DeFi protocols, and MCP server. ![The All-in-One Crypto API](https://static.coinstats.app/z/best%20crypto%20api_2.png.png) [The all-in-one crypto API](https://coinstats.app/api/). Market data, [wallets](https://coinstats.app/api/crypto-wallet/), [DeFi](https://coinstats.app/api/defi/), portfolio analytics, and token security. Cheaper per call than specialized providers, and one key replaces your entire stack. **CoinStats API = market data + wallets + DeFi + portfolio analytics + token security** Most crypto projects stitch together four or five providers. An RPC node for wallet balances. A market data feed for prices. A DeFi aggregator for protocol positions. A transaction parser for history. A scanner for token risks. CoinStats API replaces that entire stack. One key. One schema. And it costs less call by call. **Market data is cheaper than competing price APIs.** Wallet and DeFi data costs less than dedicated wallet APIs. You save twice. Once by consolidating vendors, again on every call. Wallets are the real differentiator. Most providers give you prices OR wallet data. CoinStats gives you both, tied together in one schema. Pass any address. **Get balances, full transaction history, and DeFi positions. Across 120+ chains, through one API.** Bitcoin support covers xpub, ypub, and zpub keys. HD wallets resolve automatically. DeFi positions across 10,000+ protocols are auto-detected per wallet. Staking, lending, LP positions, and yield. No manual setup, no protocol-by-protocol integrations. CoinStats API is the best fit for most crypto use cases. Portfolio trackers, trading bots, tax tools, wallet explorers, AI assistants, embedded dashboards. One key, one integration. Wallet balances, transactions, DeFi positions, prices, tickers, portfolio analytics, and token risk scores. All across every major blockchain. The platform behind this API powers the CoinStats app. Over 1M people use it every month. The same data infrastructure is available to any developer here. It also includes a dedicated [MCP Server](/docs/mcp/connecting) for AI agents and LLM-powered applications, so your code and your AI tools query the same crypto data through one provider. ## What You Get Solana, Ethereum, all EVM chains, Bitcoin, Cosmos, and 110+ more. One endpoint, one schema. Market data from Binance, Coinbase, Hyperliquid, and 200+ CEXs and DEXs. Staking, lending, LP positions, and yield data. Auto-detected, no manual setup. Real-time prices, market caps, volumes, supply data, and historical charts. Model Context Protocol support for Claude, Cursor, VS Code, and other AI tools. Start free. Scale with pricing based on endpoint complexity, not flat limits. ## Data You Get Through a Single Integration Most crypto projects need data from multiple sources: an RPC node for on-chain balances, a market data provider for prices, a DeFi aggregator for protocol positions, and yet another service for transaction parsing. CoinStats API consolidates all of these into a single endpoint, which is why it fits most crypto use cases out of the box. Real-time prices, market caps, volumes, and OHLCV charts for 100,000+ coins. Token holdings and transaction histories for any address across 120+ blockchains. Staking, lending, and LP positions across 10,000+ protocols. Auto-detected per wallet. Tickers and trading pairs from 200+ exchanges with consistent response formatting. Unified portfolio view with profit/loss, performance charts, and risk scores. Aggregated crypto news, trending topics, and sentiment data from trusted sources. Smart-contract risk analysis for any token — honeypots, malicious mint/blacklist, hidden fees, upgradeable proxies. Powered by Hexens. ## Built for Developers and AI Agents CoinStats API is a REST API with JSON responses, standard HTTP status codes, and API key authentication. If you've integrated any REST API before, you already know how this works. For AI-native applications, [the CoinStats MCP Server](/docs/mcp/connecting) exposes the same data through the Model Context Protocol, allowing LLMs and AI agents to query crypto data directly. This works with Claude, Cursor, Claude Code, VS Code (via Cline or Continue), and N8N, among other MCP clients. JSON responses, API key auth, standard HTTP status codes. Works with any language. 20+ crypto data tools for AI assistants via npx. Prices, wallets, DeFi, and more. ## Token Risks Before a user buys or a bot routes into a token, you can screen the contract for the patterns scammers actually use. The [Token Risks endpoint](/docs/openapi/token-risks) returns an overall risk score plus a severity-ranked list of findings with plain-English explanations for any token — queried by CoinStats `coinId` or a raw `contractAddress` + `chain`. It surfaces the threats that drain wallets: honeypots, centralized mint/burn, blacklists and whitelists, pausable or blockable transfers, hidden fees, upgradeable (proxy) contracts, unrenounced ownership, and balance manipulation. ### How It Works Token Risks is powered by [Hexens](https://hexens.io) and its **Glider** engine. Rather than pattern-matching bytecode, Glider reasons over the contract's functions, execution paths, and dependencies to catch logic-level threats. CoinStats maps every finding to a severity (`critical` → `minor`) and a human-readable note your UI can render directly, with coverage across EVM chains (Ethereum, BNB Chain, Polygon, Base, Arbitrum, Optimism, Avalanche, and more). ### Why It's Better Than the Alternatives Most token scanners are heuristic flag-lists: they miss logic-level scams or bury you in false positives. Per the [Glider benchmark](https://coinstats.app/blog/risks/), Glider caught every critical threat with no false positives, while competing tools missed between 40% and 75% of the same risks. And because Token Risks runs on the same platform as prices, wallets, and portfolios, it's one API key and one integration — no separate security vendor to bolt on. Query by coinId or contractAddress + chain. Score, severity-ranked findings, plain-English notes. The Hexens Glider approach and benchmark behind the Token Risks API. ## What You Can Build CoinStats API fits a wide range of crypto applications. Below are the most common use cases developers build with it, along with the endpoints and data types involved. ### Portfolio Trackers A portfolio tracker needs to pull holdings from multiple wallets and exchanges, calculate current values, and show profit/loss over time. With CoinStats API, you can query wallet balances across 120+ blockchains through [the Wallet endpoints](/docs/wallet/solana), get real-time pricing for every token from the Market Data endpoints, and aggregate everything into a single portfolio view using [the Portfolio endpoints](/docs/portfolio/portfolio-coins). The API handles the hard parts: normalizing token balances across different chains, detecting DeFi positions automatically across 10,000+ protocols, and calculating PnL with average buy/sell prices. You get a unified response whether the user holds SOL on Solana, ETH on Arbitrum, or BTC via an xpub key. ### Trading Bots and Signal Engines Trading systems need fast, reliable market data across multiple exchanges. CoinStats API aggregates pricing from 200+ centralized and decentralized exchanges, including Binance, Coinbase, and Hyperliquid. You can pull real-time tickers, compare prices across exchanges for arbitrage detection, and access historical OHLCV chart data for backtesting. The credit-based pricing model works well here: basic market data calls cost 1-2 credits each, so high-frequency polling stays cost-effective. Combine price endpoints with wallet balance checks to build systems that monitor positions and execute based on market conditions. ### Tax and Accounting Tools Crypto tax reporting requires complete transaction histories across every chain a user has touched. CoinStats API provides full transaction data for any wallet address, including token transfers, DeFi interactions, staking rewards, and LP activity. [The Bitcoin endpoint](/docs/wallet/bitcoin) supports xpub/ypub/zpub keys to capture all derived addresses from HD wallets. Each transaction includes timestamps, amounts, token identifiers, and USD values at the time of the transaction. This gives tax tools the raw data needed for cost-basis calculations (FIFO, LIFO, specific identification) without requiring users to manually export CSVs from each chain. ### Multi-Chain Wallet Explorers Building a wallet explorer that works across multiple blockchains normally requires integrating a separate data source for each chain. CoinStats API gives you a single endpoint that accepts any wallet address and returns balances, token holdings, transaction history, and DeFi positions regardless of the underlying chain. The API supports [Solana](/docs/wallet/solana), [Ethereum and all EVM chains](/docs/wallet/ethereum-evm) (Polygon, Arbitrum, Optimism, Base, BSC, Avalanche, Fantom, and more), [Bitcoin](/docs/wallet/bitcoin) (including Lightning Network), and [dozens of other networks](/docs/wallet/other-chains): Cardano, Tron, Cosmos, Polkadot, Kusama, Near, Algorand, Stellar, Ripple, Litecoin, Dogecoin, Bitcoin Cash, Hedera, VeChain, StarkNet, zkSync, Polygon zkEVM, Immutable X, Monero, Zcash, and Dash, among others. One integration covers them all. ### AI Crypto Assistants [The CoinStats MCP Server](/docs/mcp/connecting) lets AI agents query crypto data the same way a developer would use the REST API. Instead of writing custom API calls, your AI assistant connects to the MCP Server and gets access to 20+ tools for looking up prices, checking wallet balances, analyzing portfolios, fetching news, and more. This works with Claude, Cursor, Claude Code, VS Code (via Cline or Continue), and N8N. Any application that supports the Model Context Protocol can connect to CoinStats data. The MCP Server is useful for building chatbots, copilot features, automated research agents, and any product where an LLM needs structured crypto data. ### Embedded Widgets and Dashboards If you're embedding crypto data into an existing application (a fintech dashboard, a mobile wallet, a news platform), CoinStats API provides the data layer. Pull live price tickers for any coin, display portfolio summaries for connected wallets, show trending news, or build chain-specific analytics views. The API returns clean JSON that maps directly to UI components. Market data endpoints cover 100,000+ coins with real-time prices, market caps, volumes, and historical charts. All data comes from a single API key with consistent response formatting, so you don't need to normalize data from multiple providers before rendering. ## Who Uses CoinStats API CoinStats API is built on the same data infrastructure that powers the CoinStats app, used by over 1M people every month. Developers integrate the API into portfolio apps, trading platforms, DeFi dashboards, tax tools, research products, and AI agents. The free tier lets you start building immediately, and credit-based pricing scales with actual usage rather than locking you into a fixed plan. Whether you're a solo developer shipping a side project, a startup building a crypto product, or an enterprise team adding crypto data to an existing platform, the API covers the same data in the same way. No separate enterprise tier, no feature gates. The data you get on the free plan is the same data available on paid plans, just with higher credit limits. ## Get Started Get your API key from the dashboard and make your first request in minutes. Free tier included. Upgrade when you need higher credit limits. Explore every endpoint with request and response examples. ![Coinstats](https://static.coinstats.app/z/best%20crypto%20api_coinstats%20api_2.png) ## Further Reading How the major crypto data APIs stack up on coverage, pricing, and limits. A buyer's guide to wallet balance, transaction, and DeFi data providers. How blockchain APIs work, what they return, and the tools worth knowing. A beginner's guide to crypto APIs and the data they give you access to. # Connect to CoinStats MCP Source: https://coinstats.app/docs/mcp/connecting Hook AI agents into your CoinStats account through the Model Context Protocol — coin prices, portfolios, wallets, exchanges and news on tap. The CoinStats MCP server lets AI agents (Claude, Cursor, Codex, ChatGPT — anything that speaks the [Model Context Protocol](https://modelcontextprotocol.io/)) read and act on the same data the CoinStats apps use, over a single OAuth-protected HTTPS URL. There's no API key to copy and no env var to manage: each user authorises the agent against their own CoinStats account in the browser, and the agent gets a per-user token from then on. This guide is for users hooking an agent into **their own** CoinStats account. If you're a developer building a server-to-server integration that uses an `X-API-KEY` header, see [Authentication](/docs/authentication) for the API-key path instead. ## Server URL ``` https://mcp.coinstats.app/mcp ``` ## Installation ### Claude.ai / Claude Desktop Settings → **Connectors** → **Add custom connector**. Paste the server URL and click **Add**: ``` https://mcp.coinstats.app/mcp ``` A browser window opens at `coinstats.app/openapi/consent`. Sign in (or recognise your existing session), review the requested access, click **Approve**. The connector turns green and CoinStats tools become available in the same chat. ### Cursor Add to `~/.cursor/mcp.json`: ```json theme={null} { "mcpServers": { "coinstats": { "url": "https://mcp.coinstats.app/mcp" } } } ``` Restart Cursor. On first call, Cursor opens a browser window for the OAuth flow. ### Claude Code ```bash theme={null} claude mcp add coinstats --transport http https://mcp.coinstats.app/mcp ``` Claude Code opens a browser to authorise. Verify with: ```bash theme={null} claude mcp list ``` ### Codex `codex mcp add` registers the server URL but does **not** open a browser — you have to run `codex mcp login` separately to authorise: ```bash theme={null} codex mcp add coinstats --url https://mcp.coinstats.app/mcp codex mcp login coinstats ``` The login step opens `coinstats.app/openapi/consent` in your browser; approve and Codex finishes the token exchange. Verify with: ```bash theme={null} codex mcp list ``` `coinstats` should show `Auth: OAuth` once authenticated. If it shows `Not logged in`, re-run `codex mcp login coinstats`. ### Other MCP clients Any client that speaks the [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) transport with OAuth 2.1 authorization will work. Point it at `https://mcp.coinstats.app/mcp` and let the OAuth machinery do the rest — Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) is supported, so no pre-shared `client_id` is needed. ## What you can do After authorising, your agent can: * Look up real-time prices, charts and market data for 100,000+ coins * Read your CoinStats portfolio coins, P/L and performance over time * Query wallet balances and transactions across 120+ blockchains * Compare ticker pricing across 200+ exchanges * Pull crypto news (latest, trending, filtered by source or topic) Full tool catalog: [MCP tools](/docs/mcp/tools). ## Quick setup 1. Paste `https://mcp.coinstats.app/mcp` into your client's connector settings 2. Approve the consent screen in your browser 3. Ask your agent something — *"what's BTC at?"*, *"summarise today's crypto news"*, *"how is my portfolio doing?"* The agent picks up the OAuth bearer token automatically; no API key to manage. ## Authentication details For clients that want to walk through the flow manually: * **Protocol:** OAuth 2.1 with PKCE (S256) * **Authorization server:** `https://api.coin-stats.com` * **Discovery:** `GET https://mcp.coinstats.app/.well-known/oauth-protected-resource` (RFC 9728) * **Dynamic Client Registration:** supported, no pre-shared `client_id` needed * **Scope:** `coinstats` — read access to your CoinStats data * **Token transport:** `Authorization: Bearer ` * **Revocation:** `POST https://api.coin-stats.com/v1/oauth/revoke` ## Stdio fallback (developer mode) If you'd rather run the MCP server locally and authenticate with a developer API key (no per-user OAuth), you can still use the legacy stdio entry point: ```bash theme={null} npx @coinstats/coinstats-mcp ``` Set `COINSTATS_API_KEY` in the env, or wire it through your client's MCP server config. This is the right path for headless / unattended integrations where there's no human to click "Approve" — get a key from the [CoinStats API dashboard](https://openapi.coinstats.app). ```json theme={null} { "mcpServers": { "coinstats": { "command": "npx", "args": ["-y", "@coinstats/coinstats-mcp"], "env": { "COINSTATS_API_KEY": "${COINSTATS_API_KEY}" } } } } ``` ## Related * [MCP tools](/docs/mcp/tools) — full catalog of crypto data, portfolio, wallet, exchange and news tools * [Authentication](/docs/authentication) — `X-API-KEY` path for non-MCP / server-to-server integrations * [Rate limits](/docs/rate-limits) and [Credit multipliers](/docs/multipliers) — usage rules apply identically to MCP and REST * [API reference](/docs/api-reference) — the REST surface every MCP tool wraps # MCP Tools for Crypto Data Source: https://coinstats.app/docs/mcp/tools The best MCP server for crypto. 20+ tools for real-time prices, wallet balances, DeFi positions, exchange data, news, and portfolios. The best MCP server for crypto. 20+ tools for real-time prices, wallet balances, DeFi positions, exchange data, news, and portfolios. The CoinStats MCP Server gives AI assistants and LLM-powered applications structured access to the same crypto data available through [CoinStats REST API](/docs/). Instead of writing custom API calls, your AI tool connects to the MCP Server and gets 20+ tools for querying prices, checking wallet balances, tracking portfolios, fetching news, and more. Every tool maps to a CoinStats API endpoint, so the data is the same whether you use the REST API or the MCP interface. This page lists every tool available through the MCP Server. For setup instructions, see [Connecting to CoinStats MCP page](/docs/mcp/connecting). ## Why MCP for Crypto Data The Model Context Protocol (MCP) is a standard that lets AI assistants call external tools directly. Instead of a user copying data from an API and pasting it into a chat, the AI agent calls the tool itself, gets structured data back, and uses it to answer questions or take actions. For crypto applications, this matters because the data changes constantly. Prices move every second, wallet balances update with every transaction, and DeFi positions shift as protocols rebalance. An AI assistant with MCP access can pull live data on demand rather than relying on stale training knowledge. The CoinStats MCP Server is built on the same data infrastructure that powers the CoinStats app, used by over 1M people every month. It covers 100,000+ coins, 200+ exchanges, 120+ blockchains, and 10,000+ DeFi protocols, all accessible through the tools listed below. ## Available Tools ### Market Data Tools These tools provide real-time and historical pricing, market caps, volumes, and chart data for cryptocurrencies. | Tool Name | Description | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get-coins` | Get comprehensive data about all cryptocurrencies: price, market cap, volume, price changes (1h, 24h, 7d), supply information, trading metrics, social links, and metadata. | | `get-coin-by-id` | Get detailed information about a specific cryptocurrency based on its unique identifier. | | `get-coin-chart-by-id` | Get chart data for a specific cryptocurrency, specifying different time ranges. | | `get-coin-avg-price` | Get the historical average price for a specific cryptocurrency on a specific date. | | `get-coin-exchange-price` | Get the historical price data for a specific cryptocurrency on a particular exchange. | | `get-market-cap` | Get global market data: total market cap, BTC dominance, and overall market metrics. | An AI assistant with these tools can answer questions like "What's the current price of Solana?", "Show me Bitcoin's price chart for the last 30 days", or "What was the average price of ETH on January 15, 2025?" ### Wallet Tools These tools let AI agents query wallet balances and transaction histories across 120+ blockchains. | Tool Name | Description | | ------------------------- | ---------------------------------------------------------------------------------- | | `get-wallet-balance` | Get the balance data for a wallet address on a specific blockchain network. | | `get-wallet-balances` | Get the balance data for a wallet address across all CoinStats-supported networks. | | `get-wallet-sync-status` | Check the syncing status of a wallet with the blockchain network. | | `get-wallet-transactions` | Get transaction data for a specific wallet. Requires syncing transactions first. | | `transactions-sync` | Initiate the syncing process to update transaction data for a specific wallet. | With these tools, an AI assistant can look up any wallet address on any supported chain. Example queries: "What tokens does this Solana address hold?", "Show me the transaction history for this Ethereum wallet", or "What's the total value of this Bitcoin xpub?" For details on supported chains, see [Solana Wallet API](/docs/wallet/solana), [Ethereum & EVM Chains page](/docs/wallet/ethereum-evm), [Bitcoin Wallet Integration page](/docs/wallet/bitcoin), or [Multi-Chain Support page](/docs/wallet/other-chains). ### Exchange Tools These tools provide access to exchange data, including supported exchanges, tickers, and trading pairs. | Tool Name | Description | | --------------------------- | ------------------------------------------------------------------------------- | | `get-ticker-exchanges` | Get a list of supported exchanges. | | `get-ticker-markets` | Get a list of tickers for a specific cryptocurrency across different exchanges. | | `get-exchanges` | Get a list of supported exchange portfolio connections. | | `get-exchange-balance` | Get the balance data for a connected exchange account. | | `get-exchange-sync-status` | Check the syncing status of an exchange portfolio. | | `get-exchange-transactions` | Get transaction data for a specific exchange connection. | These tools are useful for comparing prices across exchanges, checking exchange-specific trading data, or building assistants that help users manage exchange portfolios. ### News Tools These tools give AI agents access to cryptocurrency news from aggregated sources. | Tool Name | Description | | ------------------ | ------------------------------------------------------------ | | `get-news-sources` | Get available news sources. | | `get-news` | Get news articles with pagination. | | `get-news-by-type` | Get news articles filtered by type (e.g., trending, latest). | | `get-news-by-id` | Get a specific news article by its ID. | An AI assistant can use these tools to summarize recent crypto news, track coverage of specific coins, or build daily market briefings. Example: "What's the latest news about Ethereum?" or "Give me a summary of today's top crypto stories." ### Portfolio Tools These tools let AI agents access CoinStats portfolio data for users who have shared their portfolio via a share token. | Tool Name | Description | | ---------------------------- | ---------------------------------------------------------------------------- | | `get-portfolio-coins` | Get a list of portfolio coins with profit/loss data and performance metrics. | | `get-portfolio-chart` | Get portfolio performance chart data over various time periods. | | `get-portfolio-transactions` | Get a list of portfolio transactions. | | `add-portfolio-transaction` | Add a transaction to a manual portfolio. | | `save-share-token` | Save a portfolio share token to local cache for future use across sessions. | | `get-share-token` | Retrieve the saved portfolio share token from local cache. | Portfolio tools require a share token for authentication. See [Share Token Authentication page](/docs/sharetoken) for setup instructions. ### Utility Tools | Tool Name | Description | | --------------------- | ----------------------------------------------------- | | `get-blockchains` | Get a list of all blockchains supported by CoinStats. | | `get-fiat-currencies` | Get a list of fiat currencies supported by CoinStats. | | `get-currencies` | Get a list of all supported currencies. | ## What You Can Build With MCP Tools ### Conversational Crypto Assistants The most common use case for MCP tools is building AI assistants that can answer crypto questions with live data. Instead of the AI guessing or relying on training data, it calls the appropriate tool, gets current information, and responds with accurate numbers. Example conversation flow: A user asks "How is my portfolio doing?" The AI calls `get-share-token` to retrieve the saved token, then `get-portfolio-coins` to get current holdings with PnL data, and responds with a summary of the user's positions, gains, and losses. No manual data entry, no copy-pasting from dashboards. ### Market Research Agents AI agents can use the market data and news tools together to produce automated research. An agent could pull the top coins by market cap, check their 24h price changes, fetch recent news about each one, and compile a daily market briefing. This is useful for trading desks, research teams, or newsletter automation. ### Wallet Monitoring Bots Combine the wallet tools with a scheduling system (like N8N) to build automated wallet monitoring. An agent can periodically sync a wallet, check for new transactions, and alert the user when something changes. This works across all 120+ supported blockchains using the same tool set. ### Portfolio Analytics Copilots For applications that already have portfolio data, the MCP tools can power a copilot feature. A user asks "Which of my holdings has the highest risk?" and the AI calls `get-portfolio-coins`, analyzes the response data (risk scores, volatility, market cap), and provides a ranked analysis. The AI does the analytical work; the MCP tools provide the data. ### IDE-Integrated Crypto Development Developers working in Cursor or VS Code can use the MCP tools to query live data while coding. Building a portfolio tracker? Ask the AI to call `get-wallet-balance` with a test address and show you the response format, right inside your editor. This is faster than switching to a browser to test API calls manually. ## MCP Clients The CoinStats MCP Server works with any client that supports the Model Context Protocol. Here are the most popular options: ### Claude The simplest setup for non-developers. Claude Desktop discovers MCP tools automatically, shows them in a sidebar, and asks for permission before calling them. Best for conversational access to crypto data. ### Cursor Developer-focused editor with built-in MCP support. One-click install available. Best for developers who want crypto data access while coding. See [Connecting page](/docs/mcp/connecting) for the quick install link. ### VS Code (via Claude Code, Cline, or Continue) Deep IDE integration for developers who prefer VS Code. Multiple MCP client extensions are available: * **Claude Code**: Chat and run tools directly in the terminal * **Cline**: File editing, terminal commands, and browsing powered by MCP * **Continue**: Flexible, extensible AI integration with MCP support ### N8N Web-based automation tool for building workflows that pull CoinStats data and trigger actions in other apps. Best for scheduled tasks, alerts, and pipeline automation. Connect the CoinStats MCP endpoint as a custom node or HTTP request step. ### Choosing the Right Client | Workflow | Best Client | | --------------------------------- | --------------- | | Chat-first, non-technical users | Claude | | Development and coding | Cursor, VS Code | | Automated workflows and pipelines | N8N | | Research and analysis | Claude, Cursor | ## Credits and Rate Limits MCP tools consume the same credits as the corresponding REST API endpoints. Market data calls cost 1-2 credits, wallet operations cost 40-50 credits, and DeFi data costs 400 credits. See [Credit Multipliers page](/docs/multipliers) and [Rate Limits page](/docs/rate-limits) for full details. The free tier includes enough credits to test all MCP tools. Credit usage is tracked through [CoinStats API dashboard](https://openapi.coinstats.app). ## Getting Started 1. Get your API key from [CoinStats API dashboard](https://openapi.coinstats.app) 2. Follow [connection guide](/docs/mcp/connecting) for your preferred client (Cursor, Claude, VS Code, or N8N) 3. Start querying: ask your AI assistant "What's the current price of Bitcoin?" and it will call `get-coin-by-id` automatically The MCP Server uses the same API key as the REST API. If you already have a key, you can connect immediately. # Credit Multipliers Source: https://coinstats.app/docs/multipliers Understanding how API credit multipliers work with dynamic pricing The CoinStats API uses a flexible credit system that can dynamically adjust costs based on the complexity and scale of your requests. ## How Credits Work Every API endpoint has a base credit cost, but some endpoints use **multipliers** to scale costs based on the parameters you provide. This ensures fair pricing - simple requests cost less, while complex requests that require more resources cost proportionally more. Simple endpoints with constant resource usage have fixed credit costs Advanced endpoints scale costs based on request complexity using multipliers ## Understanding Multipliers Multipliers allow endpoints to calculate credits based on: Parameters in the URL query string (e.g., `?networks=ethereum,polygon`) Data sent in POST/PATCH request bodies, including nested objects ## How Multiplier Calculation Works The total credit cost is calculated by applying multipliers to each parameter individually: Total Credits = Sum of (Base Credits × Multiplier for each parameter) **Important:** Multipliers can be applied multiple times within the same request. Example: ```json theme={null} "body":{ "wallets": [ {"address":"0x123...", "connectionId": "ethereum"}, {"address":"0x456...", "connectionId": "all"} ] } ``` In this scenario, if the base credit is 4, the total credits will be calculated as follows: * **Wallet 1**: `connectionId: "ethereum"` → 4 × 1 = **4 credits** * **Wallet 2**: `connectionId: "all"` → 4 × 10 = **40 credits** * **Total**: 4 + 40 = **44 credits** Each wallet is processed independently with its own multiplier based on the `connectionId` value. Here's a visual breakdown of how the system processes requests with multipliers: ```mermaid theme={null} flowchart TD A["API Request
Base Credits: 4"] --> B{Has Multipliers?} B -->|No| C[Fixed Credits
Base Cost Only] B -->|Yes| D[Analyze Each Wallet] D --> E["Wallet 1
connectionId: 'ethereum'
Multiplier: 1x"] D --> F["Wallet 2
connectionId: 'all'
Multiplier: 10x"] E --> G["Calculate Cost
4 × 1 = 4 credits"] F --> H["Calculate Cost
4 × 10 = 40 credits"] G --> I["Total Credits
4 + 40 = 44"] H --> I C --> J[Final Cost] I --> J J --> K{Credits Available?} K -->|Yes| L["✅ Request Processed"] K -->|No| M["❌ 429 Error
Credits limit reached"] ``` ### Multiplier Values Different parameters have different multiplier effects: The exact base cost depends on the endpoint. Replace `base` in these examples with the credit count shown in the endpoint docs. When you provide multiple values (comma-separated or as arrays): ```bash theme={null} # Single network = base credits ?networks=ethereum # Multiple networks = base credits × count ?networks=ethereum,polygon,binance_smart # 3× multiplier ``` Using `"all"` applies a predefined multiplier: ```bash theme={null} # Using 'all' applies default multiplier (usually 10×) ?connectionIds=all # 10× multiplier ``` **Mixed 'all' and specific values**: Combining `"all"` with other values (e.g., `connectionIds=all,ethereum,polygon`) adds extra complexity and costs. The system counts all items AND adds additional credits for the 'all' portion. Request body arrays also scale costs: ```json theme={null} { "wallets": [ {"address": "0x123...", "connectionId": "ethereum"}, {"address": "0x456...", "connectionId": "polygon"} ] } // 2× multiplier for 2 wallets = base × 2 credits ``` **With mixed multipliers:** ```json theme={null} { "wallets": [ {"address": "0x123...", "connectionId": "ethereum"}, {"address": "0x456...", "connectionId": "all"} ] } // Wallet 1: base × 1 credits, Wallet 2: base × 10 credits // Total: base × 11 credits ``` **Many 'connectionId' fields** ```json theme={null} { "wallets": [ {"address": "0x123...", "connectionId": "ethereum,polygon"} {"address": "0x456...", "connectionId": "all"} ] } // Wallet 1: base × 2 credits, Wallet 2: base × 10 credits // Total: base × 12 credits ``` **Cost Difference:** Using specific networks (`ethereum,polygon`) costs **80% less** than using `"all"` (2× base vs 10× base). Always specify only the networks you actually need! If you need all of networks/connections better use `all` instead of 10+ connectionId/network. (10× base vs 10× base+) ## Cost Optimization Tips The `"all"` value applies a **10× multiplier**. Be specific instead: ```bash theme={null} # ❌ Expensive (10× multiplier) ?connectionId=all # ✅ Much cheaper (1× multiplier each) ?connectionId=ethereum # or specify only what you need ``` **Savings:** Using specific values instead of `"all"` can reduce costs by 90% Each item in arrays gets its own multiplier. Plan your requests accordingly: ```json theme={null} // Example: base cost is the credit count shown on the endpoint { "wallets": [ {"address": "0x123...", "connectionId": "ethereum"}, // base × 1 credits {"address": "0x456...", "connectionId": "all"} // base × 10 credits ] } // Total: base × 11 credits (not base × 2 credits!) ``` **Key insight:** Mixed multipliers within the same array can create unexpected costs. Consider splitting requests when mixing standard and high-multiplier values: ```json theme={null} # ❌ Mixed request (base × 11 credits total) POST /endpoint { "wallets": [ {"connectionId": "ethereum", "address": "0x123..."}, // base × 1 credits {"connectionId": "all", "address": "0x123..."} // base × 10 credits ] } # ✅ Separate requests (base × 2 credits total if you don't actually need "all") POST /endpoint {"wallets": [{"connectionId": "ethereum", "address": "0x123..."}]} // base × 1 credits POST /endpoint {"wallets": [{"connectionId": "polygon", "address": "0x123..."}]} // base × 1 credits ``` Track your credit usage in the [CoinStats API Dashboard](https://openapi.coinstats.app) to: * Identify unexpectedly expensive requests * Find patterns where `"all"` multipliers are driving costs * Optimize requests with high multiplier combinations ## Frequently Asked Questions Multipliers ensure fair pricing based on actual resource consumption. Requesting data for 1 wallet requires fewer resources than requesting data for 100 wallets, so the pricing reflects this difference. Yes! Use endpoints with fixed pricing when possible, or make multiple smaller requests instead of one large request with many parameters. No, only specific parameters on certain endpoints use multipliers. Check each endpoint's documentation for details about which parameters are multiplied. Your requests will be rejected with a `429 Too Many Requests` error. You can upgrade your plan or wait for your credits to reset based on your plan's terms. **Pro Tip**: Start with smaller requests to understand costs, then optimize based on your actual usage patterns. The API dashboard provides detailed insights to help you optimize your credit usage. **Important**: Always test with small parameter sets first to understand the credit impact before making large batch requests. Multipliers can significantly increase costs for large parameter sets. # Add Portfolio Transaction Source: https://coinstats.app/docs/openapi/add-portfolio-transaction /api-reference/openapi.json post /v1/portfolio/transaction Add a new transaction to your manual portfolio **4** credits per request
* Support for buy, sell, and transfer operations * Automatically updates your portfolio holdings * Validates transaction data before recording * Returns the details of the created transaction * shareToken: Get this from your CoinStats portfolio page * Transaction details in request body: * coinId: The cryptocurrency's identifier * count: Amount (negative for sells) * date: Transaction timestamp (optional) * price: Price at time of transaction (optional) * notes: Add personal notes to the transaction * currency: Specify currency for price (default: USD) * passcode: Passcode for accessing protected portfolio data (can be passed in header or query parameter) # Analytics Market Signals Source: https://coinstats.app/docs/openapi/analytics-market-signals /api-reference/openapi.json get /v1/prediction/analytics/market-signals Composite whale + smart-money signals (top 50 active markets) **3** credits per request
* For the top 50 active markets, a `whaleSignal` and `smartMoneySignal` per market, with their volumes. * A `compositeSignal` and an overall `recommendation` (`STRONG_BUY`…`STRONG_SELL`). # Analytics Overview Source: https://coinstats.app/docs/openapi/analytics-overview /api-reference/openapi.json get /v1/prediction/analytics/overview Platform overview stats **3** credits per request
* High-level platform totals: event, market, and trader counts plus aggregate volume and liquidity. * Ideal for a dashboard header or "state of the platform" summary. # Btc Dominance Source: https://coinstats.app/docs/openapi/btc-dominance /api-reference/openapi.json get /v1/insights/btc-dominance Get Bitcoin market dominance data showing BTC's percentage share of the total cryptocurrency market capitalization over a specified time period **10** credits per request
* Supports multiple time frames: 24 hours, 1 week, 1 month, 3 months, 6 months, 1 year, or all available data. * Data is returned as pairs of \[timestamp, percentage] values. * Useful for analyzing market trends and Bitcoin's relative strength in the overall crypto ecosystem. * type: Time range. One of `24h`, `1w`, `1m`, `3m`, `6m`, `1y`, `all`. # Connect Portfolio Exchange Source: https://coinstats.app/docs/openapi/connect-portfolio-exchange /api-reference/openapi.json post /v1/portfolio/exchange Connect an exchange account to your account and create a tracked portfolio **10** credits per request
* A portfolioId you can use to query portfolio data (value, coins, chart, transactions, defi, snapshot) * Automatic portfolio creation with visibility set to API * connectionId: Exchange identifier (e.g., "binance"). Use GET /exchange/support for supported exchanges. * connectionFields: Exchange API credentials (apiKey, apiSecret, etc.) * name: Custom display name for the portfolio # Connect Portfolio Wallet Source: https://coinstats.app/docs/openapi/connect-portfolio-wallet /api-reference/openapi.json post /v1/portfolio/wallet Connect a wallet to your account and create a tracked portfolio **40** credits per request
* A portfolioId you can use to query portfolio data (value, coins, chart, transactions, defi, snapshot) * Automatic portfolio creation with visibility set to API * Background transaction sync initiated * address: Wallet address to connect * connectionId: Blockchain network identifier (e.g., "ethereum"). Use GET /wallet/blockchains for supported networks. * name: Custom display name for the portfolio # Delete Portfolio Source: https://coinstats.app/docs/openapi/delete-portfolio /api-reference/openapi.json delete /v1/portfolio/{portfolioId} Delete Portfolio **10** credits per requestDelete an API-created portfolio by its ID. * portfolioId: Path parameter. Must reference an existing portfolio owned by the authenticated user. # Exchange Sync Status Source: https://coinstats.app/docs/openapi/exchange-sync-status /api-reference/openapi.json patch /v1/exchange/sync Initiate syncing process for the given exchange portfolio by portfolioId. **20** credits per request
* portfolioId: Identifier of an exchange portfolio you have connected. # Fear And Greed Source: https://coinstats.app/docs/openapi/fear-and-greed /api-reference/openapi.json get /v1/insights/fear-and-greed Get the Crypto Fear & Greed Index **10** credits per request
* Crypto Fear & Greed Index which measures market sentiment from 0 (Extreme Fear) to 100 (Extreme Greed). * This indicator aggregates multiple factors including volatility, market momentum, social media, and surveys to gauge investor emotional state. * Helps identify potential market tops (greed) and bottoms (fear). # Fear And Greed Chart Source: https://coinstats.app/docs/openapi/fear-and-greed-chart /api-reference/openapi.json get /v1/insights/fear-and-greed/chart Get historical data for the Crypto Fear & Greed Index **10** credits per request
* Daily values over time with timestamps, numerical values (0-100), and classifications (Extreme Fear, Fear, Neutral, Greed, Extreme Greed). * This historical view helps track market sentiment trends and identify potential correlation with price movements. # Get Api Status Source: https://coinstats.app/docs/openapi/get-api-status /api-reference/openapi.json get /v1/status Get API status Returns the current availability status of the API. # Get Blockchains Source: https://coinstats.app/docs/openapi/get-blockchains /api-reference/openapi.json get /v1/wallet/blockchains Get the list of blockchains supported by CoinStats **1** credit per request
* All supported blockchains * Blockchain network names * Blockchain network icons * To connect your wallet to CoinStats * To display blockchain network information * In other API endpoints # Get Coin Avg Price Source: https://coinstats.app/docs/openapi/get-coin-avg-price /api-reference/openapi.json get /v1/coins/price/avg Get the historical average price of a specific cryptocurrency for a given date. **4** credits per request
* coinId: Coin identifier. * timestamp: Unix timestamp at which to compute the price. # Get Coin By Id Source: https://coinstats.app/docs/openapi/get-coin-by-id /api-reference/openapi.json get /v1/coins/{coinId} Get detailed information about a specific cryptocurrency using coinId. **1** credit per request
* coinId: Path parameter. Unique coin identifier (e.g., `bitcoin`). * currency: Display currency (defaults to USD). # Get Coin Chart By Id Source: https://coinstats.app/docs/openapi/get-coin-chart-by-id /api-reference/openapi.json get /v1/coins/{coinId}/charts Get historical chart data for a specific cryptocurrency using coinId. **3** credits per request
* coinId: Path parameter. Unique coin identifier. * period: Time range for the chart. * currency: Display currency (defaults to USD). # Get Coin Exchange Price Source: https://coinstats.app/docs/openapi/get-coin-exchange-price /api-reference/openapi.json get /v1/coins/price/exchange Get historical price data for a specific cryptocurrency on a selected exchange. **5** credits per request
* exchange: Exchange identifier. * timestamp: Unix timestamp at which to compute the price. * from: Base currency symbol to convert from. * to: Target currency symbol to convert to. # Get Coins Source: https://coinstats.app/docs/openapi/get-coins /api-reference/openapi.json get /v1/coins Get comprehensive data about all cryptocurrencies **2** credits per request
* Price, market cap, and volume * Price changes (1h, 24h, 7d, 1m) * Supply information * Trading metrics * Social links and metadata * currency: Display currency (defaults to USD). * page & limit: Control pagination. * includeRiskScore: When `true`, response includes the risk score field. * categories: Comma-separated category filters. * blockchains: Comma-separated blockchain filters. * sortBy / sortDir: Sort the result set. # Get Coins Charts Source: https://coinstats.app/docs/openapi/get-coins-charts /api-reference/openapi.json get /v1/coins/charts Get historical chart data for multiple cryptocurrencies **3** credits per requestIn **Query** field **"coinIds"**: credits are multiplied by the number of values.[**Detailed multipliers explanation**](/docs/multipliers)
* Historical price data * Values in USD, BTC, ETH * coinIds: Comma-separated list of coin identifiers. At least one is required. * period: Time range for the chart data. * currency: Display currency (defaults to USD). # Get Credit Usage Source: https://coinstats.app/docs/openapi/get-credit-usage /api-reference/openapi.json get /v1/usage/credits Get your current credit usage and remaining limit Check how many API credits you have remaining for the current billing period. * Total credits available for your subscription, including active top-ups * Credits already used * Remaining credits * Your current subscription plan # Get Currencies Source: https://coinstats.app/docs/openapi/get-currencies /api-reference/openapi.json get /v1/currencies Get the complete list of supported fiat currencies **1** credit per request
* All supported fiat currencies * Currency codes and exchange rates * To Convert cryptocurrency values to fiat * To Display fiat currency information * In other API endpoints # Get Event Source: https://coinstats.app/docs/openapi/get-event /api-reference/openapi.json get /v1/prediction/events/{slug} Get an event with its child markets **1** credit per request
* A single event by `slug` along with every market nested under it. * Use it to render an event page showing all constituent outcomes (e.g. all candidates in a race) in one request. # Get Exchange Balance Source: https://coinstats.app/docs/openapi/get-exchange-balance /api-reference/openapi.json post /v1/exchange/balance Get your cryptocurrency exchange balances **10** credits per request
* Real-time balance information * All coins and tokens in your account * Current value in USD and BTC * Available and locked amounts * connectionId: Exchange identifier (e.g., "binance", "coinbase") * connectionFields: Exchange API credentials * apiKey: Your exchange API key * apiSecret: Your exchange API secret * name: Custom name for the portfolio * Use read-only API keys when possible * Keep your API credentials secure * Enable IP restrictions on exchange side # Get Exchange Chart Source: https://coinstats.app/docs/openapi/get-exchange-chart /api-reference/openapi.json get /v1/exchange/chart Get exchange chart data for specific time ranges displayed on the CoinStats website. **50** credits per request
Make sure the exchange is synced first by calling [PATCH /sync](/docs/openapi/exchange-sync-status) for up to date infromation. * portfolioId: Identifier of an exchange portfolio you have connected. * type: Time range for the chart. * Exchange must be synced first via PATCH /exchange/sync. # Get Exchange PnL Source: https://coinstats.app/docs/openapi/get-exchange-pl /api-reference/openapi.json get /v1/exchange/pl Get exchange PnL holdings data **25** credits per request
* Holdings with the same PnL fields as portfolio coins * totalCost per coin * Summary totals for the filtered result set * portfolioId: API-connected exchange portfolio ID * coinId: Filter the result and summary by coin ID * page & limit: Control pagination # Get Exchange PnL History Source: https://coinstats.app/docs/openapi/get-exchange-pl-history /api-reference/openapi.json get /v1/exchange/pl/history Get a cash-flow-adjusted historical exchange P&L chart **25** credits per request
* Chronological period P\&L and P\&L percentage points * Deposits and withdrawals removed from investment performance * An empty result when the portfolio history is not synchronized * portfolioId: An owned exchange portfolio ID * interval: hourly, daily, weekly, monthly, or yearly * Exactly one time mode: range, or both from and to * currency: Defaults to USD # Get Exchange Sync Status Source: https://coinstats.app/docs/openapi/get-exchange-sync-status /api-reference/openapi.json get /v1/exchange/status Get syncing status of the exchange portfolio, indicating whether the portfolio is fully synced with the exchange or still in progress. **3** credits per request
* portfolioId: Identifier of an exchange portfolio you have connected. * Exchange must be synced first via PATCH /exchange/sync. # Get Exchange Transactions Source: https://coinstats.app/docs/openapi/get-exchange-transactions /api-reference/openapi.json get /v1/exchange/transactions Get transaction data for a specific exchange by portfolioId. **4** credits per request
Make sure the exchange is synced first by calling [PATCH /sync](/docs/openapi/exchange-sync-status) for up to date infromation. * portfolioId: Identifier of an exchange portfolio you have connected. * Exchange must be synced first via PATCH /exchange/sync. * page & limit: Control pagination of the transaction list. * from / to: Filter by date range (ISO 8601). * currency: Display currency for transaction values. * types: Comma-separated transaction types to filter by. * hideUnidentifiedCoins: Set to true to hide transactions of unidentified coins. Defaults to false. # Get Exchanges Source: https://coinstats.app/docs/openapi/get-exchanges /api-reference/openapi.json get /v1/exchange/support Get the list of exchange portfolio connections supported by CoinStats. **1** credit per request # Get Fiat Currencies Source: https://coinstats.app/docs/openapi/get-fiat-currencies /api-reference/openapi.json get /v1/fiats Get detailed information about fiat currencies **1** credit per request
* Complete list of supported fiat currencies * Current exchange rates * Currency symbols and names * Associated images/icons * Convert cryptocurrency values to fiat * Display fiat currency information * Access currency metadata # Get Market Source: https://coinstats.app/docs/openapi/get-market /api-reference/openapi.json get /v1/prediction/markets/{slug} Get a prediction market by slug **1** credit per request
* The full detail record for a single market by its `slug`: question, outcomes, current prices, volume/liquidity, and resolution status. * The event and tags the market belongs to. # Get Market Cap Source: https://coinstats.app/docs/openapi/get-market-cap /api-reference/openapi.json get /v1/markets Get current global cryptocurrency market data **1** credit per request
* Total market capitalization * 24h trading volume * Bitcoin dominance * Market trends and indicators # Get News Source: https://coinstats.app/docs/openapi/get-news /api-reference/openapi.json get /v1/news Get the list of cryptocurrency news articles with pagination. **5** credits per request
* page & limit: Control pagination. * from / to: Filter by date range (ISO 8601). # Get News By Id Source: https://coinstats.app/docs/openapi/get-news-by-id /api-reference/openapi.json get /v1/news/{id} Get a news article by id. **1** credit per request
* id: Path parameter. Identifier of the news item. # Get News By Type Source: https://coinstats.app/docs/openapi/get-news-by-type /api-reference/openapi.json get /v1/news/type/{type} Get cryptocurrency news articles based on a specific type. **5** credits per request
* type: Path parameter. Must be a supported news type (see GET /news/sources for the supported set). * page & limit: Control pagination. # Get News Sources Source: https://coinstats.app/docs/openapi/get-news-sources /api-reference/openapi.json get /v1/news/sources Get the list of news sources. **2** credits per request # Get Nft Collection Asset By Tokenid Source: https://coinstats.app/docs/openapi/get-nft-collection-asset-by-tokenid /api-reference/openapi.json get /v1/nft/{collectionAddress}/asset/{tokenId} Get detailed information about a specific NFT asset. **5** credits per request
* collectionAddress: Path parameter. NFT collection contract address. * tokenId: Path parameter. Identifier of the asset within the collection. # Get Nft Collection Assets By Address Source: https://coinstats.app/docs/openapi/get-nft-collection-assets-by-address /api-reference/openapi.json get /v1/nft/{collectionAddress}/assets Get the list of NFT assets associated with NFT Collection by collectionAddress. **8** credits per request
* collectionAddress: Path parameter. NFT collection contract address. * page & limit: Control pagination. * type: Filter assets by type. # Get Nft Collection By Address Source: https://coinstats.app/docs/openapi/get-nft-collection-by-address /api-reference/openapi.json get /v1/nft/collection/{collectionAddress} Get detailed information about an NFT collection using collectionAddress. **3** credits per request
* collectionAddress: Path parameter. NFT collection contract address. # Get Nfts By Wallet Source: https://coinstats.app/docs/openapi/get-nfts-by-wallet /api-reference/openapi.json get /v1/nft/wallet/{address}/assets Get list of NFT assets owned by a wallet address. **40** credits per request
* address: Path parameter. Wallet address. * page & limit: Control pagination. # Get Portfolio Chart Source: https://coinstats.app/docs/openapi/get-portfolio-chart /api-reference/openapi.json get /v1/portfolio/chart Get historical performance data to visualize your portfolio's growth over time **10** credits per request
* Total portfolio value at different time points * Performance metrics for various time ranges * Historical Profit/Loss (PnL) data * type: Specify the time range for the chart data (e.g., "24h", "1w", "1m", "1y") * shareToken OR portfolioId: Provide one of these to identify the portfolio. * shareToken: Get this from your CoinStats portfolio page by clicking "Share" * portfolioId: Use a portfolio connected via POST /portfolio/wallet or POST /portfolio/exchange * If neither is provided, returns aggregated chart for all API-connected portfolios * passcode: Passcode for accessing protected portfolio data (can be passed in header or query parameter) * currency: Display currency (defaults to USD). # Get Portfolio Coins Source: https://coinstats.app/docs/openapi/get-portfolio-coins /api-reference/openapi.json get /v1/portfolio/coins Get detailed information about all coins in your portfolio **8** credits per request
* Current holdings and their USD value * Profit/Loss (PnL) information * Performance metrics and statistics * Risk assessment scores (optional) * shareToken OR portfolioId: Provide one of these to identify the portfolio. * shareToken: Get this from your CoinStats portfolio page by clicking "Share" * portfolioId: Use a portfolio connected via POST /portfolio/wallet or POST /portfolio/exchange * If neither is provided, returns aggregated coins from all API-connected portfolios * page & limit: Control the number of results per page * includeRiskScore: Set to "true" to include risk metrics * passcode: Passcode for accessing protected portfolio data (can be passed in header or query parameter) # Get Portfolio Defi Source: https://coinstats.app/docs/openapi/get-portfolio-defi /api-reference/openapi.json get /v1/portfolio/defi Retrieve comprehensive DeFi portfolio data, including staking, liquidity pool (LP), and yield farming activities **400** credits per request
* Detailed breakdown of DeFi assets and protocols * Track staked tokens, LP positions, and earned rewards * shareToken OR portfolioId: Provide one of these to identify the portfolio. * shareToken: Get this from your CoinStats portfolio page by clicking "Share" * portfolioId: Use a portfolio connected via POST /portfolio/wallet or POST /portfolio/exchange * If neither is provided, returns DeFi data for all API-connected portfolios * passcode: Passcode for accessing protected portfolio data (can be passed in header or query parameter) # Get Portfolio List Source: https://coinstats.app/docs/openapi/get-portfolio-list /api-reference/openapi.json get /v1/portfolio/list Get a list of all API-connected portfolios **5** credits per request
* List of all portfolios connected via POST /portfolio/wallet and POST /portfolio/exchange * Each item includes portfolioId and portfolioName * Use the returned portfolioId on any portfolio endpoint (value, coins, chart, transactions, defi, snapshot) * No pagination: returns all API-connected portfolios in a single response # Get Portfolio PnL History Source: https://coinstats.app/docs/openapi/get-portfolio-pl-history /api-reference/openapi.json get /v1/portfolio/pl/history Get a cash-flow-adjusted historical portfolio P&L chart **25** credits per request
* Chronological period P\&L and P\&L percentage points * Deposits and withdrawals removed from investment performance * The effective currency, range, interval, from, and to values * interval: hourly, daily, weekly, monthly, or yearly * Exactly one time mode: range, or both from and to * portfolioId: An owned API-connected portfolio; omit it to aggregate all owned API-connected portfolios * shareToken and passcode: Access a shared CoinStats portfolio instead * currency: Defaults to USD # Get Portfolio Snapshot Items Source: https://coinstats.app/docs/openapi/get-portfolio-snapshot-items /api-reference/openapi.json get /v1/portfolio/snapshot/items Get historical portfolio snapshot data with normalized coin balances and portfolio metrics **500** credits per request
* Historical coin quantities and balances over time * Total portfolio balance tracking with changes * Price changes and quantity changes between snapshots * Filterable by date range and specific coins * shareToken OR portfolioId: Provide one of these to identify the portfolio. * shareToken: Get this from your CoinStats portfolio page by clicking "Share" * portfolioId: Use a portfolio connected via POST /portfolio/wallet or POST /portfolio/exchange * If neither is provided, returns snapshot data for all API-connected portfolios * from & to: Date range filter (YYYY-MM-DD format) * coinIds: Comma-separated list of coin IDs to filter by * page & limit: Pagination controls * passcode: Passcode for accessing protected portfolio data (can be passed in header or query parameter) # Get Portfolio Sync Status Source: https://coinstats.app/docs/openapi/get-portfolio-sync-status /api-reference/openapi.json get /v1/portfolio/status Get Portfolio Sync Status **3** credits per requestGet the syncing status of an API-created portfolio (connected via POST /portfolio/connect-wallet or POST /portfolio/connect-exchange). * portfolioId: Must reference an existing portfolio owned by the authenticated user. # Get Portfolio Transactions Source: https://coinstats.app/docs/openapi/get-portfolio-transactions /api-reference/openapi.json get /v1/portfolio/transactions Get a detailed history of all transactions in your portfolio **4** credits per request
* Complete list of buy/sell operations * Transaction dates and amounts * Price information at time of transaction * Supports pagination for viewing large transaction sets * currency: Specify the currency for price values * shareToken OR portfolioId: Provide one of these to identify the portfolio. * shareToken: Get this from your CoinStats portfolio page by clicking "Share" * portfolioId: Use a portfolio connected via POST /portfolio/wallet or POST /portfolio/exchange * If neither is provided, returns transactions from all API-connected portfolios * page & limit: Control the number of transactions per page * coinId: Filter transactions for a specific coin * passcode: Passcode for accessing protected portfolio data (can be passed in header or query parameter) * hideUnidentifiedCoins: Set to true to hide transactions of unidentified coins. Defaults to false. # Get Portfolio Value Source: https://coinstats.app/docs/openapi/get-portfolio-value /api-reference/openapi.json get /v1/portfolio/value Get detailed information about portfolio profit/loss **10** credits per request
* Total value of portfolio * Defi value of portfolio * Total cost of portfolio * Unrealized profit/loss * Realized profit/loss * All time profit/loss * shareToken OR portfolioId: Provide one of these to identify the portfolio. * shareToken: Get this from your CoinStats portfolio page by clicking "Share" * portfolioId: Use a portfolio connected via POST /portfolio/wallet or POST /portfolio/exchange * If neither is provided, returns aggregated data for all API-connected portfolios * currency: Specify the currency for price values, default is USD * passcode: Passcode for accessing protected portfolio data (can be passed in header or query parameter) # Get Ticker Exchanges Source: https://coinstats.app/docs/openapi/get-ticker-exchanges /api-reference/openapi.json get /v1/tickers/exchanges Provides a comprehensive list of cryptocurrency exchanges supported by CoinStats. **2** credits per request # Get Ticker Markets Source: https://coinstats.app/docs/openapi/get-ticker-markets /api-reference/openapi.json get /v1/tickers/markets Returns a list of tickers for a specific cryptocurrency across multiple exchanges. **3** credits per request
* coinId: Filter by coin identifier (e.g., "bitcoin"). * exchange: Filter tickers by exchange name. * fromCoin: Filter by base currency symbol of the trading pair. * toCoin: Filter by quote currency symbol of the trading pair. * onlyVerified: When true, returns only verified tickers. * page & limit: Control pagination. # Get Trader Source: https://coinstats.app/docs/openapi/get-trader /api-reference/openapi.json get /v1/prediction/traders/{address} Trader profile (enriched with live PnL, cash balance, rank) **2** credits per request
* A single trader's full profile by wallet address, enriched with live figures: current PnL, cash balance, portfolio value, and leaderboard rank. * The headline endpoint for a trader detail page. # Get Trending Nfts Source: https://coinstats.app/docs/openapi/get-trending-nfts /api-reference/openapi.json get /v1/nft/trending Get the most popular NFT collections right now **2** credits per request
* Top trending collections by volume and activity * Floor prices and market caps * Collection statistics and metadata * Trading volume and price trends * Recent sales volume * Market activity * Social engagement * Price movement * page & limit: Control pagination. # Get Wallet Balance Source: https://coinstats.app/docs/openapi/get-wallet-balance /api-reference/openapi.json get /v1/wallet/balance Get cryptocurrency balances for any blockchain wallet **40** credits per requestIn **Query** field **"connectionId"**: credits are multiplied by the number of values.If the value of **"connectionId"** in **Query** is **"all"**, multiplier is **400** credits.In **Query** field **"blockchain"**: credits are multiplied by the number of values.If the value of **"blockchain"** in **Query** is **"all"**, multiplier is **400** credits.Multipliers can be applied multiple times.[**Detailed multipliers explanation**](/docs/multipliers)
* Token balances on one or more blockchains * Current USD price, BTC price, and 24h change * Token contract addresses and decimals (ERC20-style tokens) * Market data: rank, 24h volume * address: Wallet address to query * One of connectionId or blockchain (if both provided, connectionId is used): * Single value (e.g., "ethereum") * Comma-separated values ("ethereum,polygon") * "all" — every supported network (top-tier EVM chains forced; other chains bounded by a per-chain latency limit and may be skipped) * "forceall" — every supported network, no latency limit (the response is delayed by the slowest chain) * Omit both and the networks are detected from the address itself — see "Address-only requests". * If you send just an address, the networks are worked out from the address format. * An EVM address (0x…, or an ENS name) is queried on every EVM chain, exactly like "all" — and costs the same as "all". * Any other address is queried on the first network its format is valid for (e.g. a bc1… address on Bitcoin), and costs a single-network request. * An address that matches no supported network returns 400. * The top-tier EVM chains forced under "all" are: ethereum, binacesmartchain, base-wallet, polygon-wallet, arbitrum-wallet, optimism-wallet, avalanche-wallet, hyperevm-wallet, monad-wallet, plasma-wallet. In rare cases a slow non-top-tier chain may be omitted; use "forceall" to wait for everything. # Get Wallet Balance Many Source: https://coinstats.app/docs/openapi/get-wallet-balance-many /api-reference/openapi.json get /v1/wallet/balance/many Get cryptocurrency balances for multiple wallets **40** credits per requestIn **Query** field **"networks"**: credits are multiplied by the number of values.If the value of **"networks"** in **Query** is **"all"**, multiplier is **400** credits.In **Query** field **"blockchain"**: credits are multiplied by the number of values.If the value of **"blockchain"** in **Query** is **"all"**, multiplier is **400** credits.In **Query** field **"wallets"**: credits are multiplied by the number of values.If the value of **"wallets"** in **Query** is **"all"**, multiplier is **400** credits.Multipliers can be applied multiple times.[**Detailed multipliers explanation**](/docs/multipliers)
* Token balances grouped by blockchain (and per wallet, when querying multiple) * Current USD price, BTC price, and 24h change per token * Token contract addresses and decimals (ERC20-style tokens) * Either: * wallets: comma-separated "connectionId:address" pairs (a connectionId of "all" or "forceall" is also accepted), or * address plus blockchain (single, comma-separated, "all", or "forceall"), or * address on its own — the networks are then detected from the address itself If **address** and **wallets** are sent together, **wallets** is ignored: the response covers the address only, and the ignored wallets are not charged for. * If you send just an address, the networks are worked out from the address format. * An EVM address (0x…, or an ENS name) is queried on every EVM chain, exactly like "all" — and costs the same as "all". * Any other address is queried on the first network its format is valid for (e.g. a bc1… address on Bitcoin), and costs a single-network request. * An address that matches no supported network returns 400. * "all" forces the top-tier EVM chains — ethereum, binacesmartchain, base-wallet, polygon-wallet, arbitrum-wallet, optimism-wallet, avalanche-wallet, hyperevm-wallet, monad-wallet, plasma-wallet — and bounds other chains by a per-chain latency limit, so in rare cases a slow chain may be omitted. Use "forceall" instead to wait for every supported chain regardless of latency. # Get Wallet Defi Source: https://coinstats.app/docs/openapi/get-wallet-defi /api-reference/openapi.json get /v1/wallet/defi Retrieve comprehensive DeFi portfolio data, including staking, liquidity pool (LP), and yield farming activities This endpoint is only available for OpenApi users with paid subscription.**400** credits per requestIn **Query** field **"connectionId"**: credits are multiplied by the number of values.If the value of **"connectionId"** in **Query** is **"all"**, multiplier is **4000** credits.In **Query** field **"blockchain"**: credits are multiplied by the number of values.If the value of **"blockchain"** in **Query** is **"all"**, multiplier is **4000** credits.Multipliers can be applied multiple times.[**Detailed multipliers explanation**](/docs/multipliers)
* Detailed breakdown of DeFi assets and protocols * Track staked tokens, LP positions, and earned rewards * address: Wallet address to query * One of connectionId or blockchain (if both provided, connectionId is used). Single value, comma-separated list, or "all". # get wallet profit & loss Source: https://coinstats.app/docs/openapi/get-wallet-pl /api-reference/openapi.json get /v1/wallet/pl get wallet profit & loss **25** credits per requestIn **Query** field **"connectionId"**: credits are multiplied by the number of values.If the value of **"connectionId"** in **Query** is **"all"**, multiplier is **250** credits.In **Query** field **"blockchain"**: credits are multiplied by the number of values.If the value of **"blockchain"** in **Query** is **"all"**, multiplier is **250** credits.Multipliers can be applied multiple times.[**Detailed multipliers explanation**](/docs/multipliers)
* Wallet holdings with coin details, quantities, current prices, and total cost basis. * Profit and loss breakdowns for each holding, including realized, unrealized, all-time, 24-hour, and last-trade values. * Average buy and sell prices, plus profit percentages, so you can understand how each position is performing. * A summary object with total value, total cost, profit, and profit percentage for the filtered result set. * address plus connectionId/blockchain * Raw wallet requests require transactions to be synced first with PATCH /wallet/transactions * coinId: Filter the result and summary by coin ID * page & limit: Control pagination # Get Wallet PnL History Source: https://coinstats.app/docs/openapi/get-wallet-pl-history /api-reference/openapi.json get /v1/wallet/pl/history Get a cash-flow-adjusted historical wallet P&L chart **25** credits per requestIn **Query** field **"connectionId"**: credits are multiplied by the number of values.If the value of **"connectionId"** in **Query** is **"all"**, multiplier is **250** credits.In **Query** field **"blockchain"**: credits are multiplied by the number of values.If the value of **"blockchain"** in **Query** is **"all"**, multiplier is **250** credits.Multipliers can be applied multiple times.[**Detailed multipliers explanation**](/docs/multipliers)
* Chronological period P\&L and P\&L percentage points * An aggregate across the synchronized requested wallet networks * An empty result when no requested network has synchronized history * address: Wallet address * connectionId or blockchain: One value, comma-separated values, or all * interval: hourly, daily, weekly, monthly, or yearly * Exactly one time mode: range, or both from and to * currency: Defaults to USD Use **from=2025-09-01** and **to=2025-10-01** because from is inclusive and to is exclusive. Keep **interval=daily** for daily points, or use **interval=monthly** for one value covering the month. # Get Wallet Sync Status Source: https://coinstats.app/docs/openapi/get-wallet-sync-status /api-reference/openapi.json get /v1/wallet/status Get the syncing status of the provided wallet address with the blockchain network. **3** credits per requestIn **Query** field **"connectionId"**: credits are multiplied by the number of values.If the value of **"connectionId"** in **Query** is **"all"**, multiplier is **30** credits.In **Query** field **"blockchain"**: credits are multiplied by the number of values.If the value of **"blockchain"** in **Query** is **"all"**, multiplier is **30** credits.Multipliers can be applied multiple times.[**Detailed multipliers explanation**](/docs/multipliers)
* address: Wallet address. * One of connectionId or blockchain (if both provided, connectionId is used). # Get Wallet Transactions Source: https://coinstats.app/docs/openapi/get-wallet-transactions /api-reference/openapi.json get /v1/wallet/transactions Get transaction data for wallet addresses **30** credits per requestIn **Query** field **"wallets"**: credits are multiplied by the number of values.If the value of **"wallets"** in **Query** is **"all"**, multiplier is **300** credits.[**Detailed multipliers explanation**](/docs/multipliers)
Provide **address** plus either **connectionId** or **blockchain**. Provide **wallets** parameter in format "**connectionId**:*address*,**connectionId**:*address*" * Provide either single-wallet form (`address` plus one of `connectionId` or `blockchain`; if both are provided, `connectionId` is used) or `wallets` (comma-separated `connectionId:address` pairs) for multi-wallet. * Transactions must be synced first via PATCH /wallet/transactions. * page & limit: Control pagination of the transaction list. * from / to: Filter by timestamp range. * currency: Display currency for transaction values. * types: Comma-separated transaction types to filter by. * coinId: Filter transactions by coin. * txId: Look up a specific transaction by its hash. * hideUnidentifiedCoins: Set to true to hide transactions of unidentified coins. Defaults to false. * Returns 409 Conflict if transactions have not been synced yet — call PATCH /wallet/transactions first # List Events Source: https://coinstats.app/docs/openapi/list-events /api-reference/openapi.json get /v1/prediction/events List prediction-market events **2** credits per request
* A paginated list of Polymarket events (groups of related markets). * Filter by `active` and `closed`. * Sort by `volume24hr`, `volume`, or `endDate`. # List Markets Source: https://coinstats.app/docs/openapi/list-markets /api-reference/openapi.json get /v1/prediction/markets List prediction markets **2** credits per request
* A paginated list of Polymarket prediction markets. * Filter by `active` and `eventId`. * Sort by `volume24hr`, `volume`, `liquidity`, or `endDate`. * Prices are probabilities in 0..1; money is USD. # List Traders Source: https://coinstats.app/docs/openapi/list-traders /api-reference/openapi.json get /v1/prediction/traders Trader leaderboard **2** credits per request
* A paginated trader leaderboard sortable by PnL (multiple windows), score, volume, win rate, or ROI. * Filter by `tier` (1–4) and `minDecided` (minimum number of resolved markets). # Market Bars Source: https://coinstats.app/docs/openapi/market-bars /api-reference/openapi.json get /v1/prediction/markets/{slug}/bars OHLC candles for the yes outcome **2** credits per request
* OHLC candles for the Yes outcome, derived from the venue price series (nothing stored). * Each bar `t` is the bucket start (unix seconds); `count` is how many upstream observations fell in the bucket. Empty buckets are omitted, not forward-filled. * Choose the window with `interval` (`1h`…`max`); `fidelity` sets minutes between upstream samples. # Market Orderbook Source: https://coinstats.app/docs/openapi/market-orderbook /api-reference/openapi.json get /v1/prediction/markets/{slug}/orderbook Full CLOB order-book depth for both outcomes **2** credits per request
* The live order book straight from the CLOB (never stored): best bid/ask, spread, midpoint, and best-first bid/ask levels per outcome. * Both outcome books in one call (mirrored for binary markets); use `outcome` to fetch just one, and `depth` to cap levels per side. * Summary fields (`bidLevels`, `bidDepth`, …) always describe the whole book; a one-sided book is normal near resolution. # Market Price At Source: https://coinstats.app/docs/openapi/market-price-at /api-reference/openapi.json get /v1/prediction/markets/{slug}/price-at Yes price as of a point in time **1** credit per request
* The last Yes-price observation at or before `t` (unix seconds). Never interpolates. * `price` is null when the series begins after `t`; `observedAt` is the timestamp actually used (`<= t`). * The lookback window widens with the age of `t`; override with `interval`. # Market Price History Source: https://coinstats.app/docs/openapi/market-price-history /api-reference/openapi.json get /v1/prediction/markets/{slug}/price-history Yes-price time series for a market **2** credits per request
* The historical "Yes" probability for a market as a time series, for charting how the odds have moved. * Choose the look-back window with `interval` (`1h`…`max`); `fidelity` sets minutes per data point. # Market Prices Source: https://coinstats.app/docs/openapi/market-prices /api-reference/openapi.json get /v1/prediction/markets/{slug}/prices Current prices (live from the CLOB order book) **1** credit per request
* The latest order-book pricing per outcome: best bid/ask, midpoint, and spread. * Prices are pulled live from the Polymarket CLOB order book. * Use it for a real-time price readout rather than historical trends. # Rainbow Chart Source: https://coinstats.app/docs/openapi/rainbow-chart /api-reference/openapi.json get /v1/insights/rainbow-chart/{coinId} Get Rainbow Chart data **10** credits per request
* Bitcoin or Ethereum based on the 'coinId' parameter. * The Rainbow Chart shows historical price data over time, which can be visualized with color bands representing different market sentiment zones. * An array of data points with price and time values. * coinId: Path parameter. Currently supports `bitcoin` or `ethereum`. # Search Source: https://coinstats.app/docs/openapi/search /api-reference/openapi.json get /v1/prediction/search Search events, markets, and traders **3** credits per request
* Full-text search across events, markets, and traders matching the query string `q`. * Optionally restrict to one `type` (`events`, `markets`, or `traders`). * The unified search-box backend for prediction markets. # Sync Portfolio Source: https://coinstats.app/docs/openapi/sync-portfolio /api-reference/openapi.json patch /v1/portfolio/sync Sync Portfolio **30** credits per requestIn **Query** field **"portfolioId"**: credits are multiplied by the number of values.If the value of **"portfolioId"** in **Query** is **"all"**, multiplier is **300** credits.[**Detailed multipliers explanation**](/docs/multipliers)Trigger a sync for an API-created wallet or exchange portfolio. If portfolioId is omitted, all API-created portfolios will be synced (costs 10x credits). * portfolioId: When provided, syncs only that portfolio. When omitted, syncs all portfolios owned by the user. # Token Risks Source: https://coinstats.app/docs/openapi/token-risks /api-reference/openapi.json get /v1/token-risks Get smart-contract risk analysis for a token (honeypot, mint/blacklist authority, hidden fees, upgradeable proxy, and more) — powered by Hexens **5000** credits per request
* An overall risk score (0–100) plus a detailed list of individual risk findings, each with a title, plain-English note, severity, and technical description. * Detection of common rug/scam vectors: centralized mint/burn, blacklist/whitelist, pausable/blockable transfers, hidden fees, upgradeable (proxy) contracts, ownership not renounced, balance manipulation, and more. * Powered by Hexens smart-contract security analysis. * Returns an empty `results` list when no risk data is available (e.g. non-EVM tokens or contracts not yet indexed). * Provide **either** `coinId` (CoinStats coin id, e.g. `ethereum`) **or** both `contractAddress` and `chain`. * chain: Blockchain identifier for `contractAddress` — e.g. `ethereum`, `binance_smart`, `polygon-pos`, `base`, `arbitrum-one`, `optimism`, `avalanche`. * sortBy: Set to `severity` to order findings critical → minor. Defaults to detected-risks-first. # Top Traders Source: https://coinstats.app/docs/openapi/top-traders /api-reference/openapi.json get /v1/prediction/traders/top Top traders (tier <= 2) **2** credits per request
* The top tier-1/tier-2 traders, ranked by PnL or volume (`by`). * A lighter alternative to the full leaderboard for a "top traders" widget. # Trader Activity Source: https://coinstats.app/docs/openapi/trader-activity /api-reference/openapi.json get /v1/prediction/traders/{address}/activity On-chain activity feed **2** credits per request
* The trader's raw on-chain activity feed (trades, splits, merges, redeems, and similar events). * Optionally filter to a single activity `type`. * Broader than trade history — it includes non-trade on-chain actions. # Trader Category Stats Source: https://coinstats.app/docs/openapi/trader-category-stats /api-reference/openapi.json get /v1/prediction/traders/{address}/category-stats Per-category analytics + best/worst positions **3** credits per request
* The trader's performance broken down by market category/tag: volume, PnL, win rate, and ROI per category. * Their best and worst individual positions. * `topLevelOnly` collapses to parent categories; `fresh=true` bypasses the cache. # Trader Pnl History Source: https://coinstats.app/docs/openapi/trader-pnl-history /api-reference/openapi.json get /v1/prediction/traders/{address}/pnl-history Daily cumulative-PnL series **2** credits per request
* The trader's cumulative PnL as a daily time series over the last `days` days. * For plotting an equity/PnL curve on their profile. # Trader Positions Source: https://coinstats.app/docs/openapi/trader-positions /api-reference/openapi.json get /v1/prediction/traders/{address}/positions Open positions **2** credits per request
* The trader's currently open positions with size, average price, current price, and unrealized PnL per position. * Pass `refresh=true` to force a live re-fetch instead of the stored snapshot. # Trader Score Source: https://coinstats.app/docs/openapi/trader-score /api-reference/openapi.json get /v1/prediction/traders/{address}/score Composite trader score **3** credits per request
* The trader's `totalScore` and `tier` (`ELITE`…`BEGINNER`). * The component `breakdown` (performance, consistency, volume, experience) and earned `badges`. # Trader Trade Stats Source: https://coinstats.app/docs/openapi/trader-trade-stats /api-reference/openapi.json get /v1/prediction/traders/{address}/trade-stats Aggregate trade statistics **2** credits per request
* Summary statistics over all of the trader's trades: total count and volume, fees paid, buy/sell split, average/min/max trade size, markets traded, and first/last trade dates. * A quick activity profile in one call. # Trader Trades Source: https://coinstats.app/docs/openapi/trader-trades /api-reference/openapi.json get /v1/prediction/traders/{address}/trades Trade history (newest first) **2** credits per request
* The trader's individual trade history, newest first — for an activity feed or to audit how a position was built. * Pass `refresh=true` to force a live re-fetch instead of stored trades. # Transactions Sync Source: https://coinstats.app/docs/openapi/transactions-sync /api-reference/openapi.json patch /v1/wallet/transactions Initiate syncing process to update transaction data. **50** credits per requestIn **Query** field **"connectionId"**: credits are multiplied by the number of values.If the value of **"connectionId"** in **Query** is **"all"**, multiplier is **500** credits.In **Query** field **"blockchain"**: credits are multiplied by the number of values.If the value of **"blockchain"** in **Query** is **"all"**, multiplier is **500** credits.In **Body** field **"wallets"**: credits are multiplied by the number of values.If the value of **"wallets"** in **Body** is **"all"**, multiplier is **500** credits.In **Body** field **"wallets"**: credits are multiplied by the number of values.If the value of **"wallets"** in **Body** is **"all"**, multiplier is **500** credits.Multipliers can be applied multiple times.[**Detailed multipliers explanation**](/docs/multipliers)
Provide query parameters: address plus either connectionId or blockchain.
Example: \{ **address**: "0x123...", **connectionId**: "ethereum" } Provide a body with
\{ **wallets**: \[\{ **address**: "0x123...", **connectionId**: "ethereum" }] } * Single-wallet form: query params `address` + `connectionId`. * Multi-wallet form: JSON body with `wallets` array (each item `\{ address, connectionId \}`). * At least one wallet must be provided. # Trending Events Source: https://coinstats.app/docs/openapi/trending-events /api-reference/openapi.json get /v1/prediction/events/trending Trending events **2** credits per request
* The events attracting the most activity right now, ranked by 24-hour volume. * Cap the count with `limit`. * Powers a "trending" view at the event level. # Trending Markets Source: https://coinstats.app/docs/openapi/trending-markets /api-reference/openapi.json get /v1/prediction/markets/trending Trending prediction markets (top by 24h volume) **2** credits per request
* The markets seeing the most action right now, ranked by 24-hour traded volume. * Cap the count with `limit`. * Ideal for a homepage or "trending" feed without specifying sort/filter parameters yourself. # Wallet Chart Source: https://coinstats.app/docs/openapi/wallet-chart /api-reference/openapi.json get /v1/wallet/chart Get wallet chart data for specific time ranges **40** credits per requestIn **Query** field **"connectionId"**: credits are multiplied by the number of values.If the value of **"connectionId"** in **Query** is **"all"**, multiplier is **400** credits.In **Query** field **"blockchain"**: credits are multiplied by the number of values.If the value of **"blockchain"** in **Query** is **"all"**, multiplier is **400** credits.Multipliers can be applied multiple times.[**Detailed multipliers explanation**](/docs/multipliers)
* address: Wallet address. * type: Time range for the chart. * One of connectionId or blockchain (if both provided, connectionId is used). * currency: Display currency (defaults to USD). # Wallet Chart Many Source: https://coinstats.app/docs/openapi/wallet-chart-many /api-reference/openapi.json get /v1/wallet/chart/many Get chart data for multiple wallet addresses across various networks. **40** credits per requestIn **Query** field **"wallets"**: credits are multiplied by the number of values.If the value of **"wallets"** in **Query** is **"all"**, multiplier is **400** credits.[**Detailed multipliers explanation**](/docs/multipliers)
* If **aggregated** is **true**, the response will include aggregated data for all wallets. * If **aggregated** is **false**, the response will include data for each wallet individually. * wallets: Comma-separated `connectionId:address` pairs. At least one wallet is required. * type: Time range for the chart data. * aggregated: Boolean toggling the two response shapes described in "Aggregate data" above. * currency: Display currency (defaults to USD). # Get Portfolio Chart Source: https://coinstats.app/docs/portfolio/portfolio-chart Get historical portfolio performance data for visualizing value changes over time # Portfolio Performance Chart Get historical data to visualize your portfolio's performance over various time periods. This endpoint provides time-series data showing how your portfolio value has changed, perfect for creating charts and analyzing trends. ## Key Features * **Multiple Time Ranges**: View data from 24 hours to all-time history * **Time-Series Data**: Arrays of timestamps and corresponding values * **Performance Tracking**: Track portfolio growth and declines over time * **Historical Profit/Loss**: See how your PnL has evolved * **Trend Analysis**: Identify patterns and market cycles in your portfolio You'll need a share token to access portfolio data. Share tokens are available to all CoinStats users — generate one from the **Share** button on your portfolio. Learn more about [Share Token Authentication](/docs/sharetoken). ## Get Portfolio Chart Data Retrieve historical portfolio performance data: ```bash cURL theme={null} curl -H "X-API-KEY: your-api-key" \ -H "sharetoken: YOUR_SHARE_TOKEN" \ "https://api.coinstats.app/v1/portfolio/chart?type=1w" ``` ```javascript JavaScript theme={null} const response = await fetch('https://api.coinstats.app/v1/portfolio/chart?type=1w', { headers: { 'X-API-KEY': 'your-api-key', 'sharetoken': 'YOUR_SHARE_TOKEN' } }); const chartData = await response.json(); ``` ```python Python theme={null} import requests response = requests.get( 'https://api.coinstats.app/v1/portfolio/chart', params={ 'type': '1w' }, headers={ 'X-API-KEY': 'your-api-key', 'sharetoken': 'YOUR_SHARE_TOKEN' } ) chart_data = response.json() ``` **8 credits** per request ## Headers | Header | Required | Description | | ------------ | -------- | -------------------------------------------------------------- | | `X-API-KEY` | Yes | Your CoinStats API key | | `sharetoken` | Yes | Your portfolio share token ([how to get it](/docs/sharetoken)) | | `passcode` | No | Passcode if your portfolio is protected | ## Query Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------- | | `type` | string | Yes | Time range for chart data | ### Time Range Options | Type | Description | Data Points | | ----- | ---------------- | ------------------ | | `24h` | Last 24 hours | Hourly data points | | `1w` | Last 7 days | 6-hour intervals | | `1m` | Last 30 days | Daily data points | | `3m` | Last 90 days | Daily data points | | `6m` | Last 180 days | Daily data points | | `1y` | Last 365 days | Daily data points | | `all` | All-time history | Variable intervals | ### With Passcode For passcode-protected portfolios, add the `passcode` header: ```bash theme={null} curl -H "X-API-KEY: your-api-key" \ -H "sharetoken: YOUR_SHARE_TOKEN" \ -H "passcode: 123456" \ "https://api.coinstats.app/v1/portfolio/chart?type=1m" ``` ## Example Response The response is an array of arrays, where each sub-array contains `[timestamp, value]`: ```json theme={null} { "result": [ [1701388800000, 125430.52], [1701475200000, 128945.76], [1701561600000, 126780.44], [1701648000000, 130205.18], [1701734400000, 132890.92], [1701820800000, 131450.38], [1701907200000, 134720.65] ] } ``` ### Data Format * **First element**: Unix timestamp in milliseconds * **Second element**: Portfolio value in USD at that timestamp ## Visualization Examples ### JavaScript Chart Example Using Chart.js to visualize portfolio performance: ```javascript theme={null} const response = await fetch('https://api.coinstats.app/v1/portfolio/chart?type=1m', { headers: { 'X-API-KEY': 'your-api-key', 'sharetoken': 'YOUR_SHARE_TOKEN' } }); const data = await response.json(); // Transform data for Chart.js const chartData = { labels: data.result.map(point => new Date(point[0]).toLocaleDateString()), datasets: [{ label: 'Portfolio Value (USD)', data: data.result.map(point => point[1]), borderColor: 'rgb(75, 192, 192)', tension: 0.1 }] }; // Create chart new Chart(ctx, { type: 'line', data: chartData, options: { responsive: true, plugins: { title: { display: true, text: 'Portfolio Performance - Last 30 Days' } } } }); ``` ### Python Visualization Using matplotlib to plot portfolio data: ```python theme={null} import requests import matplotlib.pyplot as plt from datetime import datetime response = requests.get( 'https://api.coinstats.app/v1/portfolio/chart', params={'type': '1m'}, headers={ 'X-API-KEY': 'your-api-key', 'sharetoken': 'YOUR_SHARE_TOKEN' } ) data = response.json() # Extract timestamps and values timestamps = [datetime.fromtimestamp(point[0]/1000) for point in data['result']] values = [point[1] for point in data['result']] # Create plot plt.figure(figsize=(12, 6)) plt.plot(timestamps, values, linewidth=2) plt.title('Portfolio Performance - Last 30 Days') plt.xlabel('Date') plt.ylabel('Value (USD)') plt.grid(True, alpha=0.3) plt.xticks(rotation=45) plt.tight_layout() plt.show() ``` ## Use Cases Build interactive dashboards showing portfolio growth over time Identify bull and bear market cycles in your portfolio Monitor progress toward investment goals with visual charts Generate historical performance reports for any time period ## Calculate Performance Metrics Use chart data to calculate custom metrics: ```javascript theme={null} async function getPortfolioMetrics(shareToken, period) { const response = await fetch( `https://api.coinstats.app/v1/portfolio/chart?type=${period}`, { headers: { 'X-API-KEY': 'your-api-key', 'sharetoken': shareToken } } ); const data = await response.json(); const values = data.result.map(p => p[1]); const firstValue = values[0]; const lastValue = values[values.length - 1]; const maxValue = Math.max(...values); const minValue = Math.min(...values); return { currentValue: lastValue, startValue: firstValue, change: lastValue - firstValue, changePercent: ((lastValue - firstValue) / firstValue * 100).toFixed(2), highValue: maxValue, lowValue: minValue, volatility: ((maxValue - minValue) / minValue * 100).toFixed(2) }; } // Usage const metrics = await getPortfolioMetrics('YOUR_SHARE_TOKEN', '1m'); console.log(`30-Day Performance: ${metrics.changePercent}%`); console.log(`Volatility: ${metrics.volatility}%`); ``` ## Comparing Time Periods Compare performance across different time ranges: ```javascript theme={null} async function comparePerformance(shareToken) { const periods = ['24h', '1w', '1m', '1y']; const results = {}; for (const period of periods) { const response = await fetch( `https://api.coinstats.app/v1/portfolio/chart?type=${period}`, { headers: { 'X-API-KEY': 'your-api-key', 'sharetoken': shareToken } } ); const data = await response.json(); const values = data.result.map(p => p[1]); const change = ((values[values.length - 1] - values[0]) / values[0] * 100).toFixed(2); results[period] = `${change}%`; } return results; } // Output example: // { '24h': '+2.4%', '1w': '+5.8%', '1m': '+12.3%', '1y': '+45.6%' } ``` ## Error Handling ```json theme={null} { "error": "shareToken is required" } ``` **Solution**: Include the share token in your request ```json theme={null} { "error": "Invalid time range type" } ``` **Solution**: Use one of the valid time range options (24h, 1w, 1m, 3m, 6m, 1y, all) ```json theme={null} { "error": "Invalid API key" } ``` **Solution**: Check that your API key is correct and active ```json theme={null} { "error": "Shared portfolio not found" } ``` **Solution**: Verify your share token is correct ```json theme={null} { "error": "Passcode required for this portfolio" } ``` **Solution**: Include the correct passcode in your request Chart data availability depends on your portfolio's history. New portfolios may have limited historical data for longer time ranges. ## Best Practices * Cache chart data and refresh periodically rather than on every page load * Use appropriate time ranges for your use case (24h for real-time, 1m for recent trends) * Check for empty arrays or null values in responses * Implement fallbacks for portfolios with limited history * Use line charts for continuous data * Add annotations for significant events (large deposits/withdrawals) * Include percentage changes in chart titles for context ## Related Endpoints Get current portfolio value and overall metrics View detailed holdings and coin-level performance Access complete transaction history Get historical portfolio snapshot data # Get Portfolio Coins Source: https://coinstats.app/docs/portfolio/portfolio-coins Get detailed information about all coins in your portfolio with profit/loss data and performance metrics # Access Your Portfolio Coins Get comprehensive information about all cryptocurrency holdings in your CoinStats portfolio, including current balances, profit/loss calculations, performance metrics, and risk assessment scores. ## Key Features * **Complete Holdings Overview**: View all coins with current balances and USD values * **Profit/Loss Tracking**: Detailed PnL data including realized, unrealized, and 24-hour changes * **Performance Metrics**: Average buy/sell prices and profit percentages * **Risk Assessment**: Optional risk scores including liquidity, volatility, and market cap metrics * **Multi-Currency Values**: Get values in USD, BTC, and ETH You'll need a share token to access portfolio data. Share tokens are available to all CoinStats users — generate one from the **Share** button on your portfolio. Learn more about [Share Token Authentication](/docs/sharetoken). ## Get Portfolio Coins Retrieve detailed information about all coins in your portfolio: ```bash cURL theme={null} curl -H "X-API-KEY: your-api-key" \ -H "sharetoken: YOUR_SHARE_TOKEN" \ "https://api.coinstats.app/v1/portfolio/coins?includeRiskScore=true" ``` ```javascript JavaScript theme={null} const response = await fetch('https://api.coinstats.app/v1/portfolio/coins?includeRiskScore=true', { headers: { 'X-API-KEY': 'your-api-key', 'sharetoken': 'YOUR_SHARE_TOKEN' } }); const data = await response.json(); ``` ```python Python theme={null} import requests response = requests.get( 'https://api.coinstats.app/v1/portfolio/coins', params={ 'includeRiskScore': 'true' }, headers={ 'X-API-KEY': 'your-api-key', 'sharetoken': 'YOUR_SHARE_TOKEN' } ) data = response.json() ``` **8 credits** per request ### Headers | Header | Required | Description | | ------------ | -------- | -------------------------------------------------------------- | | `X-API-KEY` | Yes | Your CoinStats API key | | `sharetoken` | Yes | Your portfolio share token ([how to get it](/docs/sharetoken)) | | `passcode` | No | Passcode if your portfolio is protected | ### Query Parameters | Parameter | Type | Required | Description | | ------------------ | ------- | -------- | ------------------------------------------------------ | | `page` | number | No | Page number for pagination (default: 1) | | `limit` | number | No | Number of results per page | | `includeRiskScore` | boolean | No | Set to `true` to include risk metrics (default: false) | ### With Passcode For passcode-protected portfolios, add the `passcode` header: ```bash theme={null} curl -H "X-API-KEY: your-api-key" \ -H "sharetoken: YOUR_SHARE_TOKEN" \ -H "passcode: 123456" \ "https://api.coinstats.app/v1/portfolio/coins?includeRiskScore=true" ``` ### Example Response ```json theme={null} { "result": [ { "count": 44.4987, "coin": { "rank": 2, "identifier": "ethereum", "symbol": "ETH", "name": "Ethereum", "icon": "https://static.coinstats.app/coins/1650455629727.png", "isFake": false, "isFiat": false, "priceChange24h": -5.74, "priceChange1h": 0.1, "priceChange7d": 1.12, "priceChange1m": 8.42, "volume": 61315198931.43572 }, "price": { "USD": 4343.564311034, "BTC": 0.039479708, "ETH": 1 }, "profit": { "allTime": { "USD": 83720.75297372, "BTC": 0.054246576, "ETH": -0.0008427712028833412 }, "hour24": { "USD": -11770.04265107636, "BTC": -0.055726915608058335, "ETH": 0 }, "lastTrade": { "USD": -0.0011652685976688212, "BTC": -8.325768295004658e-9, "ETH": 8.470329472543003e-22 }, "unrealized": { "USD": 64875.375139922, "BTC": 0.516615331, "ETH": -0.000013421973257266018 }, "realized": { "USD": 18844.785945298, "BTC": -0.46237401135664413, "ETH": -0.0008426785167330308 } }, "averageBuy": { "USD": 2800.50, "BTC": 0.028, "ETH": 0.95 }, "averageSell": { "USD": 3200.00, "BTC": 0.032, "ETH": 1.05 }, "profitPercent": { "allTime": { "USD": 55.2, "BTC": 41.0, "ETH": -0.09 }, "unrealized": { "USD": 42.5, "BTC": 38.2, "ETH": -0.01 }, "realized": { "USD": 14.2, "BTC": -15.5, "ETH": -0.08 } }, "liquidityScore": 94.44676177373067, "volatilityScore": 6.823477152064536, "marketCapScore": 90.15554879029162, "riskScore": 7.407055529347417, "avgChange": 2.631321607022045 } ] } ``` ## Response Fields * `count`: Amount of the coin you hold * `coin.rank`: Market cap rank * `coin.identifier`: Unique coin identifier * `coin.symbol`: Coin ticker symbol * `coin.name`: Full coin name * `coin.icon`: Coin logo URL * `coin.priceChange24h`: 24-hour price change percentage * `coin.priceChange1h`: 1-hour price change percentage * `coin.priceChange7d`: 7-day price change percentage * `coin.priceChange1m`: 1-month price change percentage * `coin.volume`: 24-hour trading volume Current prices in multiple currencies: * `price.USD`: Price in US Dollars * `price.BTC`: Price in Bitcoin * `price.ETH`: Price in Ethereum * `profit.allTime`: Total profit/loss since first purchase * `profit.hour24`: Profit/loss in the last 24 hours * `profit.lastTrade`: Profit/loss from the most recent trade * `profit.unrealized`: Profit/loss on holdings not yet sold * `profit.realized`: Profit/loss from completed sales * `averageBuy`: Average price paid when buying * `averageSell`: Average price received when selling Only included when `includeRiskScore=true`: * `liquidityScore`: Market liquidity metric (0-100) * `volatilityScore`: Price volatility metric (0-100) * `marketCapScore`: Market capitalization score (0-100) * `riskScore`: Overall risk assessment (0-100) * `avgChange`: Average price change percentage ## Use Cases Analyze your complete crypto holdings with detailed profit/loss data Monitor individual coin performance and identify top performers Use risk scores to assess portfolio volatility and liquidity Export realized and unrealized gains for tax calculations ## Pagination For portfolios with many coins, use pagination to manage results: ```bash theme={null} # Get first 20 coins curl -H "X-API-KEY: your-api-key" \ -H "sharetoken: YOUR_SHARE_TOKEN" \ "https://api.coinstats.app/v1/portfolio/coins?page=1&limit=20" # Get next 20 coins curl -H "X-API-KEY: your-api-key" \ -H "sharetoken: YOUR_SHARE_TOKEN" \ "https://api.coinstats.app/v1/portfolio/coins?page=2&limit=20" ``` ## Error Handling ```json theme={null} { "error": "shareToken is required" } ``` **Solution**: Include the share token in your request ```json theme={null} { "error": "Invalid API key" } ``` **Solution**: Check that your API key is correct and active ```json theme={null} { "error": "Shared portfolio not found" } ``` **Solution**: Verify your share token is correct ```json theme={null} { "error": "Passcode required for this portfolio" } ``` **Solution**: Include the correct passcode in your request Make sure you have a valid share token before making requests. See the [Share Token Authentication](/docs/sharetoken) guide for detailed instructions on getting your token. ## Related Endpoints Get total portfolio value and overall PnL metrics View historical portfolio performance data Access complete transaction history View staking and DeFi positions # Markets & Events Source: https://coinstats.app/docs/prediction/markets-and-events List, filter, and price Polymarket markets and events. A **market** is a single tradable question with outcomes (usually `Yes`/`No`) and a price per outcome in `0..1`. An **event** groups related markets — for example a presidential election event holds one market per candidate. ## Markets Paginate and filter by `active`, `eventId`; sort by volume, liquidity, or end date. Top markets by 24h volume. Full market detail by `slug`. Best bid/ask, midpoint, and spread per outcome. Full CLOB depth for both outcomes, best-first, live from the venue. Yes-price time series over `1h`…`max` intervals. OHLC bars for the Yes outcome at your chosen interval/fidelity. The last Yes price at or before a given timestamp (no interpolation). ```bash theme={null} # Active markets, richest first curl "https://api.polystats.ai/api/markets?active=true&sort=volume24hr&limit=20" \ -H "X-API-KEY: YOUR_API_KEY" ``` ## Events Filter by `active`, `closed`; sort by volume or end date. Top events by 24h volume. Event detail including its child markets. ```bash theme={null} # Top events right now curl "https://api.polystats.ai/api/events/trending?limit=10" \ -H "X-API-KEY: YOUR_API_KEY" ``` # Prediction Markets Source: https://coinstats.app/docs/prediction/overview Read-only analytics for Polymarket prediction markets — markets, events, traders, per-trader PnL, search, and platform analytics. One API key, one integration. Prediction markets let people trade on the outcome of real-world events — elections, sports, macro prints, crypto price levels — where each market's price *is* the crowd's probability of "Yes". CoinStats puts **Polymarket** behind one read-only API: consistent shapes, one auth scheme, and deep per-trader analytics. **Base path:** `https://api.polystats.ai/api/*` · `X-API-KEY` auth on every endpoint. Browse the full schema and try-it console under the **Prediction ·** groups (Markets, Events, Traders, Analytics, Search) in the [API reference](/docs/openapi/list-markets). The deepest coverage is on **traders** — leaderboards plus full per-trader analytics (PnL, positions, category stats, score). Markets, events, and platform analytics give you the surrounding context. ## What you get * **Markets & events** — list, filter, and sort live and resolved markets; events group related markets (e.g. every candidate in an election). * **Prices & history** — current order-book prices and Yes-price time series. * **Traders** — a leaderboard plus deep per-trader analytics: positions, trade history, daily PnL history, category stats, and a composite score. * **Platform analytics** — overview stats and composite market signals (whale + smart-money) with a buy/sell recommendation. * **Search** — search across events, markets, and traders. ## Conventions Every endpoint shares one response envelope, so you can write one client and reuse it across all the operations. * **Success:** `{ "success": true, ...payload, "timestamp": "" }`. List endpoints add a `meta` object for pagination (`total`, `limit`, `offset`, `hasMore`). * **Error:** `{ "success": false, "error": { "message": "...", "status": } }`. * **Prices** are probabilities in `0..1`. **Money** is USD. **Dates** are ISO 8601 strings. * **Identifiers:** use the domain keys — `slug` (markets/events), `conditionId` (markets), `walletAddress` (traders), `tagId` (tags). Mongo internals (`_id`, `__v`) are stripped. ## Authentication Pass your CoinStats key in the `X-API-KEY` header on every request. Generate keys at [openapi.coinstats.app](https://openapi.coinstats.app). See [Authentication](/docs/authentication) for OAuth Bearer usage. ```bash theme={null} # Trending markets curl "https://api.polystats.ai/api/markets/trending?limit=5" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```json theme={null} { "success": true, "data": [ { "source": "polymarket", "slug": "will-btc-hit-100k-2025", "question": "Will BTC hit $100k in 2025?", "outcomes": ["Yes", "No"], "outcomePrices": [0.62, 0.38], "volume24hr": 45000, "liquidity": 230000, "endDate": "2025-12-31T23:59:59.000Z" } ], "timestamp": "2025-06-19T12:00:00.000Z" } ``` ## Credits Pricing is low and scales with how heavy each call is — every endpoint costs **1–3 credits**: | Weight | Credits | Endpoints | | ----------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Read** — single object / point-in-time | 1 | `/markets/{slug}`, `…/prices`, `…/price-at`, `/events/{slug}` | | **List** — paginated lists, trending, time-series, trader sub-resources | 2 | `/markets`, `/events`, `/traders`, `…/orderbook`, `…/bars`, `…/price-history`, `/traders/{address}`, `…/positions`, `…/trades`, `…/activity`, `…/pnl-history`, `…/trade-stats` | | **Compute** — aggregation, scoring & search | 3 | `/analytics/*`, trader `…/category-stats`, `…/score`, `/search` | ## Explore the endpoints List, filter, and price markets and events. Leaderboards, per-trader PnL, and platform signals. Full request/response schema and try-it console for every endpoint. Search events, markets, and traders. # Traders & Analytics Source: https://coinstats.app/docs/prediction/traders-and-analytics Trader leaderboards and deep per-trader analytics — positions, PnL, category stats, score — plus platform-wide market signals. This is the deepest part of the API. Every trade on Polymarket is attributable to a wallet, so you can rank traders and fully reconstruct what each one is doing. Traders are identified by `walletAddress`; markets by `conditionId`. ## Traders Rank by PnL (multiple windows), score, volume, win rate, or ROI; filter by `tier`. The top tier-1/tier-2 traders by PnL or volume. Enriched profile with live PnL, cash balance, portfolio value, and rank. Current positions with cost basis and unrealized PnL. Newest-first trade history. Aggregate trade statistics plus a headline PnL summary. Per-category analytics plus best/worst positions. Composite score across performance, consistency, volume, experience. Also available per trader: [activity feed](/docs/openapi/trader-activity), [daily PnL history](/docs/openapi/trader-pnl-history), and [trade stats](/docs/openapi/trader-trade-stats). ```bash theme={null} # Top 20 traders by 30-day PnL curl "https://api.polystats.ai/api/traders?sort=pnl30d&limit=20" \ -H "X-API-KEY: YOUR_API_KEY" # A trader's category analytics (best/worst positions included) curl "https://api.polystats.ai/api/traders/0xWALLET/category-stats" \ -H "X-API-KEY: YOUR_API_KEY" ``` ## Platform analytics Platform-wide counts and volume across events, markets, and traders. Composite whale + smart-money signals with a buy/sell recommendation. ## Search Search across events, markets, and traders in one call. ```bash theme={null} # Search markets, events, and traders at once curl "https://api.polystats.ai/api/search?q=election&limit=10" \ -H "X-API-KEY: YOUR_API_KEY" ``` # Rate Limits Source: https://coinstats.app/docs/rate-limits Understanding the credit-based rate limiting system The CoinStats API uses a credit-based system for rate limiting. Different endpoints consume different amounts of credits based on the complexity and data requirements of the request. ## Credit System Each API request consumes a specific number of credits: | Endpoint Category | Credit Cost | Description | | ----------------- | ------------- | --------------------------------------------------------------------- | | Basic Market Data | 1-2 credits | Simple data like coin lists, basic info | | Detailed Data | 3-5 credits | Historical charts, detailed analytics | | Wallet Operations | 40-50 credits | Wallet balance, transaction sync (4,000 for HD wallet xpub/ypub/zpub) | | Portfolio Data | 8-10 credits | Portfolio management features | | DeFi Data | 400 credits | Comprehensive DeFi portfolio data | ## Managing Your Credits ### Check Your Usage Monitor your credit usage through the CoinStats dashboard or programmatically via the API. Use the `/usage/credits` endpoint to check your remaining credits programmatically. ```bash theme={null} curl -X GET "https://api.coinstats.app/v1/usage/credits" \ -H "X-API-KEY: your-api-key" ``` **Response:** ```json theme={null} { "totalCredits": 20000, "usedCredits": 9000, "remainingCredits": 11000, "subscription": "FREE" } ``` The `/usage/credits` endpoint is free and does not consume any credits. ### Plan Limits Different subscription plans have different credit limits: | Plan | Credits/Month | Rate Limit | Price | | -------------- | ------------- | ----------- | ------------- | | **Free** | 20,000 | 2 req/sec | Free | | **Starter** | 1,000,000 | 30 req/sec | \$49/month | | **Pro** | 5,000,000 | 30 req/sec | \$199/month | | **Business** | 80,000,000 | 100 req/sec | \$999/month | | **Enterprise** | Custom | Custom | Contact sales | View full pricing details and features ### Best Practices * **Cache responses**: Store frequently requested data locally * **Batch requests**: Combine multiple requests when possible * **Monitor usage**: Track your credit consumption * **Optimize queries**: Use filters to reduce data transfer ### Coin List Batch Limit `GET /v1/coins` accepts a maximum of **100 coin IDs** in the comma-separated `coinIds` query parameter. Split larger sets across multiple requests. The `limit` parameter controls response pagination and does not increase the 100-ID batch limit. ## Error Responses When you exceed your credit limit, you'll receive a `429 Too Many Requests` response: ```json theme={null} { "error": "Rate limit exceeded", "message": "Insufficient credits for this request" } ``` ## Credit Reset Credits are typically reset monthly based on your subscription plan. # Share Token Authentication Source: https://coinstats.app/docs/sharetoken Learn how to use share tokens to access portfolio data through the CoinStats API Share tokens provide a secure way to access portfolio data from the CoinStats app through the API. This authentication method allows you to share specific portfolio information without exposing your main API credentials. ## What is a Share Token? A share token is a unique identifier that grants API access to a specific portfolio. It's generated directly from your CoinStats portfolio and can be used to: * View portfolio holdings and balances * Access transaction history * Retrieve DeFi positions and staking data * Get portfolio performance metrics and charts * Add transactions to manual portfolios Share tokens are available to all CoinStats users — generate one from your portfolio using the **Share** button (see below). All portfolio endpoints require either a share token or proper API authentication. ## Getting Your Share Token Go to [CoinStats Portfolio](https://coinstats.app/portfolio) and make sure you are signed in to your account. In the top-right corner of the page, click on the **Share** button. Share Button Location This will bring up sharing preferences for your portfolio. Fill Title and Description and Click **Generate Link**. Make sure you understand the privacy implications of sharing your portfolio data before generating a link. In the generated URL, the segment following `/p/` is your share token. ``` https://coinstats.app/p/YOUR_SHARE_TOKEN_HERE ^^^^^^^^^^^^^^^^^^^^ This is your share token ``` Share Button Location Copy only the token portion (without additional slashes or characters). ## Passcode Protection Some portfolios may be protected with an additional passcode for extra security. If a portfolio requires a passcode, you can include it in your requests using either query parameters or headers (recommended): ### Method 1: Header (Recommended) ```bash theme={null} curl -H "X-API-KEY: your-api-key" \ -H "sharetoken: YOUR_SHARE_TOKEN" \ -H "passcode: 123456" \ "https://api.coinstats.app/v1/portfolio/value" ``` ### Method 2: Query Parameter ```bash theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/portfolio/value?shareToken=YOUR_SHARE_TOKEN&passcode=123456" ``` The passcode is an optional 6-digit code that can be set when sharing a portfolio for additional privacy protection. Headers are recommended for better security as they keep sensitive information out of URL logs. ## Using Share Tokens in API Requests Share tokens can be provided via the `sharetoken` request header (recommended) or as a query parameter. ### Method 1: Request Header (Recommended) Include the share token in the `sharetoken` header: ```bash theme={null} curl -H "X-API-KEY: your-api-key" \ -H "sharetoken: YOUR_SHARE_TOKEN" \ "https://api.coinstats.app/v1/portfolio/value" ``` With passcode: ```bash theme={null} curl -H "X-API-KEY: your-api-key" \ -H "sharetoken: YOUR_SHARE_TOKEN" \ -H "passcode: 123456" \ "https://api.coinstats.app/v1/portfolio/value" ``` ### Method 2: Query Parameter Pass `shareToken` as a query parameter: ```bash theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/portfolio/value?shareToken=YOUR_SHARE_TOKEN" ``` With passcode: ```bash theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/portfolio/value?shareToken=YOUR_SHARE_TOKEN&passcode=123456" ``` ### Hybrid Approach You can also mix query parameters and headers: ```bash theme={null} curl -H "X-API-KEY: your-api-key" \ -H "sharetoken: YOUR_SHARE_TOKEN" \ "https://api.coinstats.app/v1/portfolio/value?passcode=123456" ``` Headers take precedence over query parameters when both are provided for the same value. ## Endpoints That Use Share Tokens All portfolio-related endpoints require share tokens: Get comprehensive portfolio profit/loss data and metrics View all coins in your portfolio with current holdings and PnL Historical performance data for portfolio visualization Complete transaction history with filtering options Add new transactions to manual portfolios Staking, liquidity pools, and yield farming data Historical portfolio snapshot data over time ## Security Best Practices * Store share tokens passcode securely using environment variables * Never expose share tokens passcode in client-side code * Keep track of where you've shared your portfolio links * Consider using passcode protection for sensitive portfolios ## Error Handling Common errors when using share tokens: ```json theme={null} { "error": "shareToken is required" } ``` **Solution**: Ensure you're providing the share token either as a query parameter or header. ```json theme={null} { "error": "Shared portfolio not found" } ``` **Solution**: Verify that your share token is correct and the portfolio still exists. ```json theme={null} { "error": "Passcode required for this portfolio" } ``` **Solution**: Include the correct passcode in your request parameters. ```json theme={null} { "error": "You are not allowed to add transactions to this portfolio" } ``` **Solution**: This error occurs when trying to add transactions to a portfolio you don't own or to non-manual portfolios. # Token Security Source: https://coinstats.app/docs/token-risks Token security API for any token — honeypot, mint/blacklist, hidden-fee and upgradeable-proxy detection. Powered by Hexens. Risk score plus severity-ranked findings. Anyone can deploy a token in minutes, and a large share of new tokens are built to take your users' money: contracts you can buy but never sell, hidden mint functions that dilute holders to zero, blacklists that freeze wallets, or "upgradeable" logic whose rules change after people ape in. The CoinStats **token security** API (the Token Risks endpoint) screens a token's smart contract *before* a user buys or a bot routes into it. You get an overall risk score plus a severity-ranked list of findings, each with a plain-English explanation you can show directly in your UI. **Endpoint:** `GET /token-risks` · **5000 credits** per request · `X-API-KEY` auth. See the [API reference](/docs/openapi/token-risks) for the full schema. ## What "token risk" means A token risk is a property of the contract that lets the deployer (or the code itself) harm holders — by seizing funds, blocking trades, silently changing balances, or changing the rules later. These are *logic-level* problems, not price or market problems: a token can have great volume and still be a honeypot. ## Risk categories Every finding comes back with a `title`, a `severity`, a `value` (`"true"` = the risk is present), a plain-English `note`, and a technical `description`. The main categories: The deployer keeps privileged control over the token or its funds. * **Centralized Mint** — *Dev can print new tokens anytime* (dilutes holders to zero). * **Centralized Burn** — *Dev can delete your tokens.* * **Balance Manipulation** — *Dev can secretly change your balance.* * **Unauthorized Token Approvals** — *Dev can spend your tokens without asking.* * **Asset Withdrawal** — *Dev can drain the contract's tokens.* * **ETH Balance Sweep** — *Dev can drain the contract's ETH.* The contract can stop specific users (or everyone) from selling. * **Blacklist** — *Dev can block certain wallets from trading.* * **Whitelist** — *Only approved wallets can trade.* * **Blockable Transfer** — *Dev can stop you from sending tokens.* * **Pausable** — *Dev has a freeze button for all trades.* * **Cooldown checks** — *You need to wait before sending again.* What you send isn't what arrives, or transfers aren't recorded faithfully. * **Hidden fees** — *Surprise taxes on every move.* * **Basic Transfer Fee** — *Hidden fee on each transfer.* * **Transfer event amount mismatch** — *What you see isn't what was sent.* * **No Transfer event emitted** — *Transfers happen without any record* (breaks explorers/indexers). * **Approval event not emitted** — *Approvals happen invisibly.* The contract can change after you buy, or is deliberately hard to verify. * **Proxy (Upgradeable)** / **Upgradeable** — *Rules can change after you buy / code can be swapped anytime.* * **Selfdestruct** — *Token can delete itself and your money.* * **External call in transfer** — *Hidden code executes during transfers.* * **Assembly usage in transfer** — *Code is complex and hard to verify.* * **Not fully ERC20 compliant** — *Token doesn't follow standard token rules.* ## How it works Token Risks is powered by [Hexens](https://hexens.io) and its **Glider** engine. Instead of pattern-matching bytecode, Glider reasons over the contract's functions, execution paths, and dependencies to find logic-level threats. CoinStats then shapes the result into a stable response: * **`score`** — overall risk, `0–100`. Higher means riskier. * **`results[]`** — individual findings, each with `severity` (`critical` → `high` → `medium` → `low` → `minor`), a plain-English `note`, and a technical `description`. * **`marketEndorsed`** — whether the token is endorsed by market consensus. * **`ownershipRenounced`** — whether contract ownership has been renounced (no owner = many owner-powers can't be used). Coverage spans EVM chains — Ethereum, BNB Chain, Polygon, Base, Arbitrum, Optimism, Avalanche, and more. Non-EVM tokens (e.g. Bitcoin) or contracts not yet indexed return an empty `results` list. ## Why it's better than the alternatives Most token scanners are heuristic flag-lists: they miss logic-level scams or bury you in false positives. Per the [Glider benchmark](https://coinstats.app/blog/risks/), Glider caught **every critical threat with no false positives**, while competing tools missed **between 40% and 75%** of the same risks. And because Token Risks runs on the same platform as prices, wallets, and portfolios, it's one API key and one integration — no separate security vendor to bolt on, and the same data that powers risk warnings for 1M+ CoinStats users. ## Using the API Query by CoinStats `coinId` **or** a raw `contractAddress` + `chain` pair. Optional `sortBy=severity` orders findings critical → minor. ```bash theme={null} # By CoinStats coin id curl "https://api.coinstats.app/v1/token-risks?coinId=shiba-inu&sortBy=severity" \ -H "X-API-KEY: YOUR_API_KEY" # By contract address + chain curl "https://api.coinstats.app/v1/token-risks?contractAddress=0xdac17f958d2ee523a2206206994597c13d831ec7&chain=ethereum" \ -H "X-API-KEY: YOUR_API_KEY" ``` Example response (abridged): ```json theme={null} { "score": 80, "marketEndorsed": true, "ownershipRenounced": false, "risksProviderUrl": "https://hexens.io/blog/glider-api-new-benchmark-in-smart-contract-security", "results": [ { "key": "risk_blockable_transfer", "value": "true", "title": "Blockable Transfer", "subtitle": "Transfers can be blocked for specific senders using various checks", "note": "Dev can stop you from sending tokens", "description": "The token's transfer logic includes pausing / cooldown / large-amount checks that can freeze certain holders.", "severity": "medium" } ], "learnMoreUrl": "https://coinstats.app/blog/risks/" } ``` `value` uses the strings `"true"` / `"false"` (Hexens wire format). `"true"` means the risk **is present**. A `200` with an empty `results` array means no risk data is available for that token (non-EVM or not yet indexed) — not "safe". Full request/response schema, parameters, and try-it console. The Hexens Glider approach and the benchmark behind it. # Bitcoin Wallet API with xpub Support Source: https://coinstats.app/docs/wallet/bitcoin The best free Bitcoin wallet API with xpub/ypub/zpub support. Track balances, transactions, derived addresses, and portfolio performance. The best free Bitcoin wallet API with xpub/ypub/zpub support. Track balances, transactions, derived addresses, and portfolio performance. Bitcoin wallet tracking is harder than other chains because of how HD (hierarchical deterministic) wallets work. A single user might have hundreds of derived addresses under one master key, and querying them individually is impractical. Most wallet apps, hardware wallets, and exchanges use HD wallets, which means a Bitcoin address lookup tool that only supports individual addresses is missing most of the picture. CoinStats Bitcoin API solves this by accepting extended public keys (xpub, ypub, zpub), so you can track all addresses in an HD wallet through a single API call. The API also supports single-address tracking for simpler use cases, and returns full transaction history with timestamps and USD values at the time of each transaction. The same Bitcoin wallet data is available through [CoinStats MCP Server](/docs/mcp/connecting) for AI agents and LLM-powered tools, so AI assistants can query Bitcoin wallets directly. ## What You Get Track all derived addresses from an HD wallet with a single extended public key. Query any individual Bitcoin address for balance and transaction history. Every transaction with timestamps, amounts, and USD values at time of transaction. Unspent transaction output information for advanced wallet analysis. Legacy (1...), SegWit (3...), Native SegWit (bc1...), and Taproot (bc1p...) all supported. Historical portfolio value charts for tracking Bitcoin holdings over time. ## Why xpub Support Matters When a user sets up a Bitcoin wallet (whether it's a Ledger, Trezor, Exodus, or any BIP-39 compatible wallet), the wallet software generates a master key. Every time the user receives a payment, the wallet creates a new address derived from that master key. After a few months of use, a single wallet might have 50, 100, or even 500 derived addresses. Without xpub support, a portfolio tracker or tax tool would need the user to manually list every address they've ever used. This is impractical and error-prone. With xpub support, you pass the extended public key once, and the API discovers all derived addresses automatically. This is how most production Bitcoin wallet integrations work. The CoinStats API accepts xpub, ypub (SegWit-wrapped), and zpub (Native SegWit) keys. All three work the same way: pass the key, get balances and transactions across all derived addresses. ## Extended Public Key (xpub) Tracking ### xpub vs Single Address | Feature | xpub Tracking | Single Address | | ------------- | ---------------------- | --------------------------- | | Coverage | All derived addresses | One address only | | UTXO tracking | Complete | Per address | | Credit cost | 4,000 credits | 40 credits | | Use case | Wallet apps, tax tools | Block explorers, monitoring | Use xpub when you need a full picture of a user's Bitcoin wallet. Use single address when you're tracking a specific known address, like a deposit address or a cold storage address. ```bash xpub Balance theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/balance?address=xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiKrhko4egpiMZbpiaQL2jkwSB1icqYh2cfDfVxdx4df189oLKnC5fSwqPfgyP3hooxujYzAu3fDVmz&connectionId=bitcoin" ``` ```javascript JavaScript theme={null} const response = await fetch( 'https://api.coinstats.app/v1/wallet/balance?address=xpub6CUGRUonZSQ4TWtTMmzXdr...&connectionId=bitcoin', { headers: { 'X-API-KEY': 'your-api-key' } } ); const balance = await response.json(); ``` ```python Python theme={null} import requests response = requests.get( 'https://api.coinstats.app/v1/wallet/balance', params={ 'address': 'xpub6CUGRUonZSQ4TWtTMmzXdr...', 'connectionId': 'bitcoin' }, headers={'X-API-KEY': 'your-api-key'} ) balance = response.json() ``` **4,000 credits** per xpub request (covers all derived addresses) The higher credit cost reflects the computational work involved: the API needs to derive all addresses from the extended public key, check each one for balances and transactions, and aggregate the results. For most applications, this is a worthwhile trade-off compared to building your own derivation and scanning infrastructure. ## Single Address Tracking For simpler use cases where you only need one address: ```bash cURL theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/balance?address=bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh&connectionId=bitcoin" ``` ```javascript JavaScript theme={null} const response = await fetch( 'https://api.coinstats.app/v1/wallet/balance?address=bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh&connectionId=bitcoin', { headers: { 'X-API-KEY': 'your-api-key' } } ); const balance = await response.json(); ``` **40 credits** per request ### Example Bitcoin Balance Response ```json theme={null} [ { "coinId": "bitcoin", "amount": 0.5, "name": "Bitcoin", "symbol": "BTC", "price": 96500.00, "priceBtc": 1.0, "imgUrl": "https://static.coinstats.app/coins/1650455588819.png", "pCh24h": 2.1, "rank": 1, "volume": 28000000000, "chain": "bitcoin" } ] ``` The response format is the same as other chains in the CoinStats API: an array of token objects with amount, price, 24h change, and volume. For Bitcoin, the array typically contains one entry (BTC), but for xpub queries it aggregates the total balance across all derived addresses. ## Transaction History Retrieve complete transaction history for a Bitcoin address or xpub: ```bash cURL theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/transactions?address=bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh&connectionId=bitcoin&limit=20" ``` ```javascript JavaScript theme={null} const response = await fetch( 'https://api.coinstats.app/v1/wallet/transactions?address=bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh&connectionId=bitcoin&limit=20', { headers: { 'X-API-KEY': 'your-api-key' } } ); const transactions = await response.json(); ``` **30 credits** per request. Sync transactions first using PATCH `/wallet/transactions`. Each transaction record includes the timestamp, BTC amount, transaction hash, and the USD value at the time of the transaction. This is particularly important for tax tools, which need the fair market value at the time of each transaction for cost-basis calculations. The API also distinguishes between received and sent transactions, which simplifies gain/loss computation. ## Portfolio Performance Get historical portfolio value over time: ```bash theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/balance/chart?address=bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh&connectionId=bitcoin&period=1y" ``` Returns time-series data for rendering portfolio performance charts. Supported periods: 1d, 1w, 1m, 3m, 6m, 1y, all. This is useful for showing users how their Bitcoin holdings have performed over time, or for calculating returns over specific periods. ## Credit Costs at a Glance | Endpoint | Credits | Description | | ---------------------- | ------- | -------------------------------------- | | Single address balance | 40 | BTC balance for one address | | xpub balance | 4,000 | Total BTC across all derived addresses | | Transaction history | 30 | Paginated transaction list | | Transaction sync | 50 | Index latest transactions | | Portfolio chart | 40 | Historical portfolio value | The xpub endpoint costs more because it involves deriving and scanning all child addresses. For most wallet apps and tax tools, this is a single call per user session, making it cost-effective compared to building your own Bitcoin address scanning infrastructure. ## What You Can Build With Bitcoin Wallet Data ### Tax and Accounting Tools Bitcoin tax reporting is complex because HD wallets generate new addresses for each transaction. Without xpub support, a tax tool would need users to manually identify and submit every address they've ever used. Some users don't even know which addresses their wallet has generated, making manual submission unreliable. The CoinStats API handles this automatically: pass the xpub key, and the API returns transactions across all derived addresses with USD values at the time of each transaction. This gives you the raw data for FIFO, LIFO, or specific identification cost-basis methods. Each transaction includes the timestamp, BTC amount, and historical USD price, which is everything a tax engine needs. For users who have held Bitcoin across multiple wallets over time, your application can accept multiple xpub keys and aggregate the transaction history across all of them. The response format is consistent regardless of whether you query one xpub or one address, so the same parsing code handles both. ### Bitcoin Portfolio Trackers For portfolio apps, the balance endpoint returns current holdings with real-time USD valuation, and the chart endpoint provides historical performance data. Combined with transaction history, you can show users their total BTC holdings, unrealized gains/losses, average cost basis, and portfolio performance over any time period. A typical flow: user enters their xpub key (which they can export from their wallet software), your app calls the balance endpoint to get the current total, calls the chart endpoint for a performance graph, and calls the transaction endpoint for a full activity log. Three API calls give you a complete Bitcoin portfolio view. ### Custody and Cold Storage Monitoring Institutional users and custody solutions need to monitor Bitcoin held across multiple addresses and cold storage wallets. The xpub endpoint tracks all addresses under a master key, while single-address tracking works for known deposit or cold storage addresses. Both return the same response format, making it easy to aggregate across wallet types. For organizations that use multi-signature wallets, the API can track each cosigner's xpub independently, giving a combined view of the multisig holdings. The UTXO data in the response is useful for custody solutions that need to verify the unspent outputs backing the wallet's balance. ### Bitcoin Payment Verification If you're building a payment processing system or a merchant tool that accepts Bitcoin, the single-address endpoint can verify that a payment has arrived at a specific address. Sync the address first, then query the transaction history to see if the expected payment has been confirmed. The response includes confirmation status and timestamps. ### AI-Powered Bitcoin Analysis Through [CoinStats MCP Server](/docs/mcp/connecting), AI agents can check Bitcoin wallet balances, look up transaction history, and analyze portfolio performance using natural language. An AI assistant can answer questions like "What's the balance of this xpub?" or "Show me the transaction history for this Bitcoin address." This is useful for building research tools, chatbots, or copilot features that need Bitcoin wallet data. ## Bitcoin vs. Other Chains The CoinStats API uses the same endpoint format across all supported chains. If your application needs wallet data beyond Bitcoin, you can query Solana, Ethereum, EVM chains, and 120+ other networks by changing the `connectionId` parameter. See [Solana Wallet API](/docs/wallet/solana), [Ethereum & EVM Chains page](/docs/wallet/ethereum-evm), or [Multi-Chain Support page](/docs/wallet/other-chains). ## Address Format Support The API accepts all standard Bitcoin address formats. The address type is detected automatically. | Format | Prefix | Example | | ---------------------- | --------- | ---------------------------------------------------------------- | | Legacy | `1...` | `1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa` | | SegWit (P2SH) | `3...` | `3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy` | | Native SegWit (Bech32) | `bc1q...` | `bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh` | | Taproot (Bech32m) | `bc1p...` | `bc1p5d7rjq7g6rdk2yhzks9smlaqtedr4dekq08ge8ztwac72sfr9rusxg3297` | | xpub | `xpub...` | Extended public key for HD wallets | | ypub | `ypub...` | SegWit-wrapped extended public key | | zpub | `zpub...` | Native SegWit extended public key | ## Getting Started 1. Sign up at [CoinStats API dashboard](https://openapi.coinstats.app) and generate an API key 2. Try the single-address balance endpoint with the cURL example above 3. For HD wallet tracking, export your xpub from your wallet software and use the xpub endpoint 4. Explore the full endpoint reference in [API docs](/docs/openapi/get-coins) The free tier includes enough credits to test all Bitcoin endpoints. No credit card required to start. ## Common Bitcoin Addresses For testing and development: | Type | Address | Description | | -------------- | -------------------------------------------- | ------------------------- | | Genesis Block | `1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa` | Satoshi's genesis address | | SegWit Example | `bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh` | Native SegWit address | # Ethereum API & EVM Wallet Balances Source: https://coinstats.app/docs/wallet/ethereum-evm The best free Ethereum API with EVM wallet tracking. Balances, transactions, DeFi, and gas data for Polygon, Arbitrum, Base, and more. [The best free Ethereum API](https://coinstats.app/api/ethereum/) with EVM wallet tracking. Balances, transactions, DeFi, and gas data for Polygon, Arbitrum, Base, and more. Most developers building on Ethereum need data from multiple EVM chains at once. A user might hold ETH on mainnet, USDC on Arbitrum, LP tokens on Polygon, and staked assets on Base. Querying each chain separately means running multiple RPC connections, normalizing different response formats, and maintaining a growing list of chain-specific integrations. CoinStats Ethereum API handles all of this through a single endpoint: pass any EVM address and get balances across every supported chain in one response. The API covers Ethereum mainnet and all major EVM-compatible chains. DeFi positions, gas fee data, and ERC-20 token holdings are included automatically. No RPC nodes, no separate indexers, no per-chain parsing logic. The same data is also available through [CoinStats MCP Server](/docs/mcp/connecting) for AI agents and LLM-powered applications. ## Supported EVM Chains The original smart contract platform. Layer 2 scaling solution. Binance Smart Chain (BSC). Optimistic rollup L2. Gaming-optimized Arbitrum L2. Optimistic Ethereum L2. High-throughput C-Chain. Coinbase L2. DAG-based smart contracts. Consensys zkEVM L2. Native yield L2. zkEVM rollup. Modular L2 network. Modular L2 for dApps. Crypto.com EVM chain. Community-owned EVM chain. Mobile-first EVM chain. NEAR's EVM layer. BNB Chain optimistic L2. Proof-of-liquidity EVM chain. Cosmos-based EVM chain. Cosmos EVM hub. Consumer-focused L2. ApeCoin L2 network. New EVM chains are added regularly. Use the `/wallet/blockchains` endpoint to get the current complete list programmatically. ## Why Multi-Chain EVM Matters The EVM ecosystem is no longer just Ethereum mainnet. Over the past two years, user activity and liquidity have migrated across Layer 2 networks, sidechains, and alternative L1s. A wallet that had all its assets on Ethereum in 2022 now likely has tokens spread across Arbitrum, Base, Polygon, and Optimism. Any application that only queries Ethereum mainnet is showing its users an incomplete picture. The CoinStats API solves this by treating all EVM chains as a single data source. One address, one API call, all chains. The response groups balances by chain, so you can show per-chain breakdowns or aggregate everything into a single total. This is the same data infrastructure that powers the CoinStats app used by over 1M people every month. ## What You Get Get balances across all EVM chains with one request. No per-chain integration needed. All token standards detected automatically per wallet address. Staking, lending, LP positions, and yield farming data across EVM DeFi protocols. Track gas consumption and fee spending per wallet across chains. ## Single Chain Balance Get wallet balance for a specific EVM chain when you only need one network: ```bash Ethereum theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/balance?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&connectionId=ethereum" ``` ```bash Polygon theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/balance?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&connectionId=polygon" ``` ```bash Arbitrum theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/balance?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&connectionId=arbitrum" ``` **40 credits** per chain per request Single-chain queries are useful for applications that only care about one network, like an Ethereum-specific block explorer or a Polygon-focused DeFi dashboard. For most portfolio and wallet applications, the multi-chain endpoint below is the better choice. ## Multi-Chain Balance (Recommended) Get wallet balances across all EVM chains simultaneously. This is the recommended approach for portfolio trackers and wallet explorers, since most users hold assets on multiple chains. ```bash All EVM Chains theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/balances?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&blockchain=all" ``` ```javascript JavaScript theme={null} const response = await fetch( 'https://api.coinstats.app/v1/wallet/balances?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&blockchain=all', { headers: { 'X-API-KEY': 'your-api-key' } } ); const balances = await response.json(); ``` ```python Python theme={null} import requests response = requests.get( 'https://api.coinstats.app/v1/wallet/balances', params={'address': '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', 'blockchain': 'all'}, headers={'X-API-KEY': 'your-api-key'} ) balances = response.json() ``` **400 credits** for all chains, or **40 credits x number of specified chains** ### Example Multi-Chain Response ```json theme={null} [ { "blockchain": "ethereum", "balances": [ { "coinId": "ethereum", "amount": 5.2, "name": "Ethereum", "symbol": "ETH", "price": 2450.30, "priceBtc": 0.0253, "pCh24h": 3.2, "rank": 2, "volume": 12000000000, "chain": "ethereum", "contractAddress": null }, { "coinId": "usd-coin", "amount": 1000.0, "name": "USD Coin", "symbol": "USDC", "price": 1.0, "pCh24h": 0.1, "rank": 5, "chain": "ethereum", "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" } ] }, { "blockchain": "polygon", "balances": [...] }, { "blockchain": "arbitrum", "balances": [...] } ] ``` The response groups balances by chain, so you can show per-chain breakdowns or aggregate everything into a single portfolio value. Each token includes its contract address, making it straightforward to link to block explorers like Etherscan or Arbiscan, or to render token icons from on-chain metadata. ## Transaction History Retrieve transaction history for a specific EVM chain: ```bash cURL theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/transactions?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&connectionId=ethereum&limit=20" ``` ```javascript JavaScript theme={null} const response = await fetch( 'https://api.coinstats.app/v1/wallet/transactions?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&connectionId=ethereum&limit=20', { headers: { 'X-API-KEY': 'your-api-key' } } ); const transactions = await response.json(); ``` **30 credits** per request. Sync transactions first using PATCH `/wallet/transactions` for the most up-to-date data. Transaction history includes token transfers, DEX swaps, DeFi protocol interactions, contract calls, and native ETH transfers. Each record includes timestamps, amounts, and gas fees, which is what tax tools and portfolio analytics need. ## Portfolio Chart Data Get historical portfolio value over time for an EVM wallet: ```bash theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/balance/chart?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&connectionId=ethereum&period=1m" ``` This returns time-series data suitable for rendering portfolio performance charts. Supported periods include 1d, 1w, 1m, 3m, 6m, 1y, and all. The data points include timestamps and USD values, ready to plug into charting libraries like Chart.js, Recharts, or D3. ## Credit Costs at a Glance | Endpoint | Credits | Description | | ------------------------------ | ------- | ------------------------------------ | | Single chain balance | 40 | All tokens on one EVM chain | | Multi-chain balance (all) | 400 | All tokens across all EVM chains | | Multi-chain balance (specific) | 40 x N | All tokens on N specified chains | | Transaction history | 30 | Paginated transaction list per chain | | Transaction sync | 50 | Index latest transactions | | Portfolio chart | 40 | Historical portfolio value | ## What You Can Build With EVM Wallet Data ### Multi-Chain Portfolio Trackers The multi-chain balance endpoint is designed for portfolio apps where users connect an Ethereum address and expect to see holdings across every EVM chain, not just mainnet. One API call returns balances for Ethereum, Polygon, Arbitrum, Optimism, Base, BSC, Avalanche, and all other supported chains. This removes the need to integrate separate data sources for each network. A typical integration: user connects their wallet (via WalletConnect or by pasting an address), your app calls the multi-chain balance endpoint, and the response contains everything needed to render a portfolio dashboard. Token names, symbols, amounts, prices, 24h changes, and chain identifiers are all included. No second API call needed for pricing. ### Cross-Chain DeFi Dashboards DeFi activity is spread across chains. A user might have staked ETH on mainnet via Lido, LP positions on Uniswap V3 (Polygon), and yield farming on Aave (Arbitrum). Building a DeFi dashboard that shows all of this normally requires integrating each protocol on each chain separately. The CoinStats API detects DeFi positions automatically across all EVM chains, so you can build dashboards that aggregate DeFi exposure without integrating each protocol individually. Staking, lending, LP positions, and yield data are returned as part of the wallet balance response. This covers 10,000+ DeFi protocols across all supported chains. ### Gas Fee Analytics For wallets that are active across multiple EVM chains, gas spending can be significant, especially on Ethereum mainnet. The API tracks gas consumption per wallet, giving analytics tools and portfolio trackers the data needed to show total fees paid across chains, fee breakdowns by network, and historical gas trends. This is particularly useful for power users and institutional accounts that want to understand their total cost of on-chain activity across all networks, not just the token gains and losses. ### Tax and Accounting Tools EVM transaction histories can be complex: token approvals, multi-hop swaps, flash loans, LP deposits and withdrawals, airdrops, and bridge transfers. The CoinStats API parses these into structured transaction records with timestamps, amounts, and token identifiers. Tax tools can use this data for cost-basis calculations across all EVM chains without building chain-specific transaction parsers. ### Embedded Crypto Widgets If you're building a fintech app, a banking dashboard, or a web3-enabled platform that needs to display EVM wallet data, the API provides the data layer. Pull live token balances, show portfolio value charts, or display transaction activity. The response format is consistent across all chains, so one set of UI components works for every network. ### AI-Powered EVM Assistants Through [CoinStats MCP Server](/docs/mcp/connecting), AI agents can look up any EVM wallet address and get balances across all chains, check specific token holdings, and analyze transaction history. An AI assistant can answer questions like "What tokens does this address hold on Arbitrum?" or "Show me the DeFi positions for this wallet." This works with Claude, Cursor, and other MCP-compatible tools. ## EVM vs. Other Chains The same endpoint format and response structure works across all CoinStats-supported chains. If your application needs Solana, Bitcoin, or other non-EVM chain data alongside Ethereum, see [Solana Wallet API](/docs/wallet/solana), [Bitcoin Wallet Integration page](/docs/wallet/bitcoin), or [Multi-Chain Support page](/docs/wallet/other-chains). ## Connection IDs Reference | Chain | Connection ID | Native Token | | --------------- | --------------- | ------------ | | Ethereum | `ethereum` | ETH | | Polygon | `polygon` | POL | | BNB Smart Chain | `binance` | BNB | | Arbitrum | `arbitrum` | ETH | | Arbitrum Nova | `arbitrum-nova` | ETH | | Optimism | `optimism` | ETH | | Avalanche | `avalanche` | AVAX | | Base | `base` | ETH | | Fantom | `fantom` | FTM | | Linea | `linea` | ETH | | Blast | `blast` | ETH | | Scroll | `scroll` | ETH | | Mantle | `mantle` | MNT | | Manta Pacific | `manta` | ETH | | Cronos | `cronos` | CRO | | Gnosis | `gnosis` | xDAI | | Celo | `celo` | CELO | | Aurora | `aurora` | ETH | | opBNB | `opbnb` | BNB | | Berachain | `berachain` | BERA | | Kava EVM | `kava` | KAVA | | Evmos | `evmos` | EVMOS | | Abstract | `abstract` | ETH | | Ape Chain | `ape` | APE | Use the `/wallet/blockchains` endpoint to get the current complete list. New EVM chains are added regularly, so this table may not always reflect the latest additions. ## Getting Started 1. Sign up at [CoinStats API dashboard](https://openapi.coinstats.app) and generate an API key 2. Try the multi-chain balance endpoint with the cURL example above 3. Explore the full endpoint reference in [API docs](/docs/openapi/get-coins) The free tier includes enough credits to test all EVM endpoints. No credit card required to start. ## Common EVM Addresses For testing and development: | Type | Address | Description | | ------------- | -------------------------------------------- | --------------------------- | | Vitalik | `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045` | Well-known Ethereum address | | USDC Contract | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` | USDC on Ethereum mainnet | ## Further Reading Ethereum and EVM providers compared for wallet, DeFi, and market data. A beginner's guide to Ethereum APIs and what they return. How the major crypto data APIs stack up on coverage, pricing, and limits. A buyer's guide to wallet balance, transaction, and DeFi data providers. # Multi-Chain Crypto Wallet API Source: https://coinstats.app/docs/wallet/other-chains The best crypto wallet API for 120+ blockchains: Cardano, Tron, Litecoin, Cosmos, and Layer 2 networks. One integration for all chains. [The best crypto wallet API](https://coinstats.app/api/crypto-wallet/) for 120+ blockchains: Cardano, Tron, Litecoin, Cosmos, and Layer 2 networks. One integration for all chains. Beyond Solana, Ethereum, and Bitcoin, CoinStats API supports dozens of additional blockchain networks. The same endpoint format works across all of them: pass a wallet address and a connection ID, and get balances, token holdings, and transaction history regardless of the underlying chain. No chain-specific integrations, no separate SDKs, no different response formats. Building multi-chain wallet support from scratch means integrating a different data source for each blockchain: a Cardano node for ADA balances, a Tron API for TRC-20 tokens, a Cosmos LCD endpoint for staking data, and so on. Each chain has its own address format, transaction structure, and token standard. CoinStats API normalizes all of this into a single response format, which is why it fits most multi-chain use cases out of the box. This page covers the non-EVM, non-Solana, non-Bitcoin chains. For chain-specific documentation, see [Solana Wallet API](/docs/wallet/solana), [Ethereum & EVM Chains page](/docs/wallet/ethereum-evm), or [Bitcoin Wallet Integration page](/docs/wallet/bitcoin). All wallet data is also accessible through [CoinStats MCP Server](/docs/mcp/connecting) for AI agents. ## Supported Blockchains ### Major Layer 1 Blockchains Proof-of-stake smart contracts. Native tokens, staking rewards, and pool delegation. High-throughput blockchain. TRC-20 tokens, energy, bandwidth, and DeFi protocols. Digital silver. Fast transactions, mining rewards, and SegWit support. Popular meme-based cryptocurrency with active community and merchant adoption. Cross-border payment network for fast, low-cost international transfers. Bitcoin fork with larger block sizes for higher transaction throughput. Internet of blockchains. IBC-connected chains, staking, and governance. Multi-chain interoperability protocol with parachains and shared security. Developer-friendly sharded blockchain with human-readable addresses. Pure proof-of-stake blockchain with instant finality. Enterprise payment network for cross-border settlements. Enterprise-grade public network with hashgraph consensus. ### Layer 2 and Scaling Solutions Bitcoin Layer 2 payment channels for fast BTC transfers. ZK-rollup scaling solution for Ethereum. Matter Labs ZK scaling platform. Zero-knowledge Ethereum scaling. ZK-rollup for gaming and digital asset applications. ### Additional Networks The API also supports VeChain, Kusama, Monero, Zcash, Dash, and more. Use the blockchains endpoint below to get the full, current list. New chains are added regularly based on user demand. ## Why One API for All Chains The typical approach to multi-chain wallet tracking looks like this: integrate the Cardano Blockfrost API for ADA, the TronGrid API for TRX, the Cosmos LCD for ATOM, and so on. Each integration has its own authentication, rate limits, response format, and error handling. Maintaining five chain integrations is manageable. Maintaining twenty is a full-time job. CoinStats API replaces all of these with a single integration. The endpoint format is identical for every chain: `/wallet/balance?address={address}&connectionId={chain}`. The response is always an array of token objects with the same fields: coinId, amount, name, symbol, price, 24h change, rank, volume, and chain. Your application code handles Cardano the same way it handles Tron, Litecoin, or any other chain. This is the same data infrastructure that powers the CoinStats app, used by over 1M people every month. The multi-chain wallet data has been battle-tested at scale. ## Get Supported Chains Retrieve the complete list of supported blockchains programmatically: ```bash cURL theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/blockchains" ``` ```javascript JavaScript theme={null} const response = await fetch( 'https://api.coinstats.app/v1/wallet/blockchains', { headers: { 'X-API-KEY': 'your-api-key' } } ); const chains = await response.json(); ``` ```python Python theme={null} import requests response = requests.get( 'https://api.coinstats.app/v1/wallet/blockchains', headers={'X-API-KEY': 'your-api-key'} ) chains = response.json() ``` **1 credit** per request ### Example Response ```json theme={null} [ { "name": "Cardano", "connectionId": "cardano", "chain": "cardano", "icon": "https://static.coinstats.app/coins/cardano.png" }, { "name": "Litecoin", "connectionId": "litecoin", "chain": "litecoin", "icon": "https://static.coinstats.app/coins/litecoin.png" }, { "name": "Tron", "connectionId": "tron", "chain": "tron", "icon": "https://static.coinstats.app/coins/tron.png" } ] ``` We continuously add support for new chains. The blockchains endpoint always returns the current list, so you can dynamically build chain selectors in your UI. ## Universal Wallet Tracking Every supported chain uses the same endpoint format. Pass the wallet address and the chain's connection ID: ```bash Cardano theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/balance?address=addr1qxy2lpan99fcnf2du5et5gw9qz8w8ky8f8m4lnhfg2r6e9a4zhk3ey7m8f4n8k7e8d5u8m8h3g2f9b8z2y3r6v9x8s&connectionId=cardano" ``` ```bash Tron theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/balance?address=TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH&connectionId=tron" ``` ```bash Litecoin theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/balance?address=LQTpS7F9y5xPMxbNGqPjRzPz8k7hGa9Xqm&connectionId=litecoin" ``` ```bash Dogecoin theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/balance?address=DH5yaieqoZN36fDVciNyRueRGvGLR3mr7L&connectionId=dogecoin" ``` ```bash Cosmos theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/balance?address=cosmos1fl48vsnmsdzcv85q5d2q4z5ajdha8yu34mf0eh&connectionId=cosmos" ``` **40 credits** per request The response format is identical across all chains: an array of token objects with amount, price, 24h change, market cap rank, and volume. This means your application code can handle any chain without chain-specific parsing logic. One function queries any wallet on any chain. ## Chain-Specific Features While the API provides a unified interface, some chains have unique capabilities worth noting: ### Cardano (ADA) Cardano wallets can include staking delegation, native token holdings (not just ADA), and pool rewards. The API captures all of these, so portfolio trackers can show staked ADA alongside freely available balances. Staking rewards are particularly important for tax tools, since they're considered taxable income in many jurisdictions. ```bash Balance theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/balance?address=addr1qxy2lpan99fcnf2du5et5gw9qz8w8ky8f8m4lnhfg2r6e9a4zhk3ey7m8f4n8k7e8d5u8m8h3g2f9b8z2y3r6v9x8s&connectionId=cardano" ``` ```bash Transactions theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/transactions?address=addr1qxy2lpan99fcnf2du5et5gw9qz8w8ky8f8m4lnhfg2r6e9a4zhk3ey7m8f4n8k7e8d5u8m8h3g2f9b8z2y3r6v9x8s&connectionId=cardano&types=executed" ``` ### Tron (TRX) Tron wallets involve TRC-20 tokens (similar to ERC-20 on Ethereum), energy/bandwidth resource management, and DeFi protocol interactions (JustSwap, SUN.io). The API tracks all TRC-20 holdings and DeFi positions. Tron's USDT volume makes it one of the most actively used chains for stablecoin transfers, so wallet tracking tools that support Tron cover a significant portion of global crypto activity. ```bash theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/balance?address=TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH&connectionId=tron" ``` ### Litecoin (LTC) Litecoin tracking works similarly to Bitcoin, supporting both single addresses and transaction history with mining reward detection. Litecoin is commonly held as a long-term asset, so portfolio trackers that include LTC alongside BTC and ETH cover the major "legacy" crypto holdings. ```bash theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/transactions?address=LQTpS7F9y5xPMxbNGqPjRzPz8k7hGa9Xqm&connectionId=litecoin" ``` ### Cosmos (ATOM) Cosmos wallets involve IBC transfers between chains, staking with validators, and governance participation. The Cosmos ecosystem includes dozens of IBC-connected chains (Osmosis, Juno, Akash, etc.), and users frequently move tokens between them. The CoinStats API tracks balances and transactions on the Cosmos Hub, with the connection ID `cosmos`. ## Credit Costs | Endpoint | Credits | Description | | ------------------- | ------- | --------------------------------------- | | Wallet balance | 40 | All tokens for one address on one chain | | Transaction history | 30 | Paginated transaction list | | Transaction sync | 50 | Index latest transactions | | Blockchains list | 1 | Get all supported chains | The same credit costs apply across all chains. There's no premium pricing for less common networks. ## What You Can Build With Multi-Chain Wallet Data ### Unified Portfolio Dashboards Most crypto users hold assets across multiple chains. A single user might have ADA staked on Cardano, TRX on Tron, LTC as a long-term hold, DOGE from 2021, and tokens spread across several EVM chains. Building a portfolio dashboard that covers all of this normally requires integrating 5-10 different blockchain APIs, each with its own authentication, response format, and rate limits. CoinStats API lets you query all of these through the same endpoint format, aggregate the results into a single portfolio value, and render per-chain breakdowns without writing chain-specific code. The response format is identical across all chains, so one component in your UI handles every network. ### Cross-Chain Tax Reporting Tax tools need transaction histories from every chain a user has touched. Since CoinStats API uses the same endpoint and response format for all chains, you can loop through a user's wallet addresses and pull transaction data without maintaining separate integrations. Each transaction includes timestamps, amounts, and token identifiers for cost-basis calculations. For chains like Cardano where staking rewards are common, the transaction history captures reward distributions as distinct transactions. This is important because staking rewards are typically taxed as income at the time of receipt, separate from any capital gains when the tokens are later sold. ### Institutional Custody Monitoring Organizations holding crypto across multiple blockchains need a single data source that covers all their chains. The CoinStats API provides this without requiring separate node infrastructure or chain-specific indexers for each network. One API key, one integration, every chain. This is particularly relevant for funds and custody providers that hold diversified crypto portfolios across Layer 1 chains. ### Wallet Comparison and Analytics Tools If you're building analytics tools that compare wallet activity across chains, the uniform response format makes it straightforward. Query a Cardano address and a Tron address, and you get back the same data structure. This lets you build chain-agnostic analytics: total holdings by chain, per-chain allocation percentages, and cross-chain activity timelines. ### AI-Powered Multi-Chain Assistants Through [CoinStats MCP Server](/docs/mcp/connecting), AI agents can query any supported blockchain using the same tool set. An AI assistant can check a Cardano wallet balance, look up Tron transactions, and aggregate holdings across chains, all through natural language queries. This works with Claude, Cursor, Claude Code, and other MCP-compatible tools. The MCP Server is particularly useful for multi-chain queries because the AI agent can query several chains in sequence and aggregate the results, just like a developer would with the REST API. No per-chain configuration needed on the AI side. ## Comprehensive Chain List | Category | Chains | Count | | ------------------ | -------------------------------------------------------------------- | ----- | | **Layer 1** | Bitcoin, Ethereum, Cardano, Solana, Polkadot, Cosmos, Near, Algorand | 8+ | | **EVM Compatible** | Polygon, BSC, Arbitrum, Optimism, Avalanche, Fantom, Base | 20+ | | **Layer 2** | Lightning, Polygon zkEVM, StarkNet, zkSync, Immutable X | 10+ | | **Enterprise** | Tron, Stellar, Ripple, Hedera, VeChain | 8+ | | **Community** | Dogecoin, Litecoin, Bitcoin Cash | 5+ | | **Privacy** | Monero, Zcash, Dash | 3+ | Use the `/wallet/blockchains` endpoint to get the current complete list, as we continuously add support for new chains. ## Getting Started 1. Sign up at [CoinStats API dashboard](https://openapi.coinstats.app) and generate an API key 2. Call the `/wallet/blockchains` endpoint to see all supported chains 3. Query any wallet address with the balance endpoint examples above 4. Explore the full endpoint reference in [API docs](/docs/openapi/get-coins) The free tier includes enough credits to test all multi-chain endpoints. No credit card required to start. ## Sample Addresses by Chain For testing and development: | Chain | Address | Type | | -------- | ------------------------------------------------------------------------------------------------- | ------------- | | Cardano | `addr1qxy2lpan99fcnf2du5et5gw9qz8w8ky8f8m4lnhfg2r6e9a4zhk3ey7m8f4n8k7e8d5u8m8h3g2f9b8z2y3r6v9x8s` | Standard | | Tron | `TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH` | TRC-20 active | | Litecoin | `LQTpS7F9y5xPMxbNGqPjRzPz8k7hGa9Xqm` | Standard | | Dogecoin | `DH5yaieqoZN36fDVciNyRueRGvGLR3mr7L` | Standard | | Cosmos | `cosmos1fl48vsnmsdzcv85q5d2q4z5ajdha8yu34mf0eh` | Standard | ## Further Reading A buyer's guide to wallet balance, transaction, and DeFi data providers. What a wallet API does, what it returns, and when you need one. How blockchain APIs work, what they return, and the tools worth knowing. How the major crypto data APIs stack up on coverage, pricing, and limits. # Solana API: Wallet Balances & Transactions Source: https://coinstats.app/docs/wallet/solana The best free Solana API for wallet balances, SPL token holdings, and complete transaction history. DeFi position tracking included. [The best free Solana API](https://coinstats.app/api/solana/) for wallet balances, SPL token holdings, and complete transaction history. DeFi position tracking included. If you're building anything on Solana that needs wallet data, whether that's a portfolio tracker, a DeFi dashboard, a tax tool, or an AI assistant, the CoinStats Solana API is a good fit for most use cases. One endpoint returns native SOL balances, all SPL token holdings, and full transaction history for any Solana address. DeFi positions across protocols like Raydium, Orca, Jupiter, and Marinade are detected automatically, so you don't need to integrate each protocol separately. The alternative is running your own Solana RPC node, parsing raw transaction data, maintaining a token registry, and building indexing infrastructure for DeFi protocols. CoinStats handles all of that. You get clean, structured JSON with current prices, USD valuations, and 24h changes included in every response. The same Solana wallet data is also available through [CoinStats MCP Server](/docs/mcp/connecting), so AI agents and LLM-powered tools can query Solana wallets directly without custom API calls. ## What You Get All SPL tokens in a wallet returned in a single call with current prices, market data, and 24h changes. SOL balance with real-time USD valuation, BTC price, and volume data. Every transaction with detailed metadata: amounts, timestamps, token identifiers, and USD values. Staking, lending, and LP positions across Solana DeFi protocols detected per wallet automatically. Query multiple Solana wallets in a single request for aggregated portfolio views. Current market prices, 24h change percentages, and volume for every token in the response. ## Why This Matters for Solana Developers Solana's architecture makes wallet data harder to work with than most chains. Transactions are packed into blocks at high throughput, token accounts are separate from the main wallet account, and DeFi interactions span dozens of programs with different data formats. Building a reliable wallet data pipeline from scratch means running an RPC node (or paying for a premium one), parsing instruction data for each DeFi protocol, and maintaining a token metadata registry. CoinStats API abstracts all of this. You send a wallet address, and the response comes back with every token, every balance, current prices, and DeFi positions already resolved. The data is the same infrastructure that powers the CoinStats app used by over 1M people every month. ## Get Wallet Balance Retrieve all tokens and SOL balance for a Solana wallet: ```bash cURL theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/balance?address=7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU&connectionId=solana" ``` ```javascript JavaScript theme={null} const response = await fetch( 'https://api.coinstats.app/v1/wallet/balance?address=7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU&connectionId=solana', { headers: { 'X-API-KEY': 'your-api-key' } } ); const data = await response.json(); ``` ```python Python theme={null} import requests response = requests.get( 'https://api.coinstats.app/v1/wallet/balance', params={'address': '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU', 'connectionId': 'solana'}, headers={'X-API-KEY': 'your-api-key'} ) data = response.json() ``` **40 credits** per request ### Example Response ```json theme={null} [ { "coinId": "solana", "amount": 2.5, "name": "Solana", "symbol": "SOL", "price": 185.42, "priceBtc": 0.00191, "imgUrl": "https://static.coinstats.app/coins/1614160068120.png", "pCh24h": 5.2, "rank": 6, "volume": 2450000000, "chain": "solana" }, { "coinId": "serum", "amount": 150.0, "name": "Serum", "symbol": "SRM", "price": 0.42, "priceBtc": 0.0000043, "imgUrl": "https://static.coinstats.app/coins/1598880399409.png", "pCh24h": -2.1, "rank": 234, "volume": 15000000, "chain": "solana" } ] ``` The response includes every token in the wallet with its current price, amount held, 24h price change, market cap rank, and trading volume. This is enough data to render a complete portfolio view without making additional API calls for pricing. Each token also includes an image URL, so you can render token icons directly from the response. ## Get Transaction History Retrieve complete transaction history for a Solana wallet: ```bash cURL theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/transactions?address=7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU&connectionId=solana&limit=10" ``` ```javascript JavaScript theme={null} const response = await fetch( 'https://api.coinstats.app/v1/wallet/transactions?address=7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU&connectionId=solana&limit=10', { headers: { 'X-API-KEY': 'your-api-key' } } ); const transactions = await response.json(); ``` ```python Python theme={null} import requests response = requests.get( 'https://api.coinstats.app/v1/wallet/transactions', params={ 'address': '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU', 'connectionId': 'solana', 'limit': 10 }, headers={'X-API-KEY': 'your-api-key'} ) transactions = response.json() ``` **30 credits** per request. Make sure to sync transactions first using PATCH `/wallet/transactions`. Transaction data includes token transfers, DeFi protocol interactions (swaps, LP deposits/withdrawals, staking), program invocations, and native SOL transfers. Each record has a timestamp and the token amounts involved, which is what tax tools need for cost-basis calculations. ## Sync Transactions Before retrieving transaction data, sync the wallet to ensure up-to-date information: ```bash cURL theme={null} curl -X PATCH \ -H "X-API-KEY: your-api-key" \ -H "Content-Type: application/json" \ "https://api.coinstats.app/v1/wallet/transactions?address=7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU&connectionId=solana" ``` ```javascript JavaScript theme={null} const response = await fetch( 'https://api.coinstats.app/v1/wallet/transactions?address=7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU&connectionId=solana', { method: 'PATCH', headers: { 'X-API-KEY': 'your-api-key', 'Content-Type': 'application/json' } } ); ``` **50 credits** per sync request The sync step is important because Solana transaction data is indexed asynchronously. Calling sync before querying ensures you get the latest transactions, including recent DeFi interactions, token swaps, and staking activity. For applications that need near-real-time data, sync the wallet on each user session or at regular intervals. ## Multiple Wallets Query multiple Solana wallets in a single request: ```bash theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/wallet/transactions?wallets=solana:7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU,solana:8yKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAtZ" ``` This is useful for portfolio trackers where a user has multiple Solana wallets, or for applications that need to aggregate balances across several addresses into a single view. Many Solana users maintain separate wallets for DeFi, long-term holdings, and active trading, so multi-wallet support covers a common real-world pattern. ## Credit Costs at a Glance | Endpoint | Credits | Description | | ------------------- | ------------- | ----------------------------------------- | | Wallet balance | 40 | All tokens + SOL balance for one address | | Transaction history | 30 | Paginated transaction list | | Transaction sync | 50 | Index latest transactions before querying | | Multi-wallet query | 30 per wallet | Transactions for multiple addresses | Credit-based pricing means you pay based on what you actually call. Basic market data calls cost 1-2 credits, while wallet operations cost more because they involve on-chain data indexing. The free tier includes enough credits to build and test your integration before scaling. ## What You Can Build With Solana Wallet Data ### DeFi Portfolio Tracking Solana's DeFi ecosystem spans Raydium, Orca, Jupiter, Marinade, Drift, Mango, and dozens of other protocols. Each protocol has its own program structure and account layout, making it difficult to aggregate DeFi exposure from raw on-chain data. The CoinStats Solana API detects DeFi positions automatically per wallet address, so you don't need to integrate each protocol separately. Build dashboards that show a user's staking rewards alongside LP positions, yield farming returns, and token balances, all from a single API call. The response normalizes everything into the same format: token, amount, current price, 24h change. This means your frontend code doesn't need protocol-specific rendering logic. ### Token Portfolio Analysis For portfolio tracking apps, the balance endpoint returns everything you need in one call: token amounts, current USD values, 24h price changes, and market cap rankings. Combined with the transaction history endpoint, you can calculate profit/loss, average buy prices, and holding period returns for each SPL token. A typical integration flow: call the balance endpoint to get current holdings, call the transaction history endpoint to get the buy/sell history, then calculate PnL by comparing current prices to average cost basis. The API provides USD values for each token, so you don't need a separate price feed. ### Transaction Monitoring and Tax Reporting The transaction history endpoint returns every transaction a wallet has made, including token transfers, DeFi interactions, staking rewards, and program invocations. Each transaction includes timestamps and token identifiers, giving tax tools the raw data needed for cost-basis calculations without requiring users to connect directly to Solana RPC nodes. For tax reporting, the key data points are: when a token was acquired, at what price, when it was sold or transferred, and at what price. The CoinStats API provides all of this. The transaction sync step ensures you capture the latest activity, including any DeFi yield that has been claimed or compounded. ### Wallet Explorers and Address Lookup Tools If you're building a Solana block explorer or address lookup tool, the balance endpoint gives you a complete snapshot of any wallet's holdings. Unlike raw RPC calls that return account data in binary format, the CoinStats API response includes human-readable token names, symbols, prices, and image URLs. This means you can render a full wallet view directly from the API response. ### AI-Powered Solana Assistants Through [CoinStats MCP Server](/docs/mcp/connecting), AI agents can look up any Solana wallet balance, check token holdings, and retrieve transaction history using natural language queries. An AI assistant can answer questions like "What's in this Solana wallet?" or "How much SOL does this address hold?" by querying the MCP Server directly. This is useful for building chatbots, copilot features, research tools, or any product where an LLM needs structured Solana data. The MCP Server wraps the same endpoints documented on this page, so the data is identical whether you use the REST API or the MCP interface. ## Solana vs. Other Chains If your application needs wallet data beyond Solana, the CoinStats API uses the same endpoint format and response structure across all supported chains. The same code that queries a Solana wallet can query an Ethereum address, a Bitcoin xpub, or a Cardano wallet by changing the `connectionId` parameter. See [Ethereum & EVM Chains page](/docs/wallet/ethereum-evm), [Bitcoin Wallet Integration page](/docs/wallet/bitcoin), or [Multi-Chain Support page](/docs/wallet/other-chains) for chain-specific documentation. ## Getting Started 1. Sign up at [CoinStats API dashboard](https://openapi.coinstats.app) and generate an API key 2. Make your first balance request with the cURL example above 3. Explore the full Solana endpoint in [API Reference](/docs/openapi/get-coins) The free tier includes enough credits to test all Solana endpoints. No credit card required to start. ## Common Solana Addresses For testing and development: | Type | Address | Description | | --------- | ---------------------------------------------- | ----------------------- | | Exchange | `7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU` | Sample exchange wallet | | DeFi User | `9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM` | Active DeFi participant | Always sync transaction data before querying for the most accurate results. ## Further Reading The Solana data providers compared on coverage, pricing, and free tiers. A developer's guide to what Solana APIs do and how to pick one. A buyer's guide to wallet balance, transaction, and DeFi data providers. How the major crypto data APIs stack up on coverage, pricing, and limits.