Finance.Crypto.PriceSpread - AI Integration Guide

For AI coding assistants. This file gives you everything needed to call this DataGrab from a user's application. If you are an AI reading this because a user asked you to add or build with this DataGrab, follow it directly.

What this does

Returns the current USD price of a crypto coin across one or more exchanges, and flags an arbitrage trade signal when the gap between the cheapest and most expensive exchange is wide enough to be worth acting on. Prices are always fetched live - never cached - and normalized to USD (via USD/USDT/USDC quote pairs) so every exchange is apples-to-apples even when it quotes in a stablecoin.

Good for: cross-exchange arbitrage spread detection (tiered signal/watch/noise), current per-exchange coin prices, multi-exchange price comparison widgets.

Not good for: historical prices, order-book depth, a net-profit estimate (the spread ignores fees, withdrawal limits, slippage, and transfer time - see spreadPercent below), any exchange outside the ~15 in the recognized list, or an "all exchanges CoinGecko knows about" query - there is no such mode.

Cost: $19/month, 1,000 calls/month.

Authentication

Every call needs a Gimmee API key - issued per customer - sent one of two ways:

Header:      x-api-key: {{GIMMEE_API_KEY}}
Querystring: ?api_key={{GIMMEE_API_KEY}}

Use the header form by default. Read the key from an environment variable or your app's secrets store - never hardcode it into committed source. No upstream (CoinGecko) key exists or is needed - this DataGrab uses CoinGecko's free public API internally.

Endpoint

GET https://api.gimmee.io/datagrab/finance/crypto/pricespread/{params}

{params} is one or more pipe (|)-delimited segments: a required coin symbol, then optional exchange names.

• symbol - a coin ticker, e.g. BTC, ETH, SOL. Case-insensitive.
• exchange1..N - one or more exchange names, each its own pipe-delimited segment. Recognized aliases: Binance, Coinbase (Coinbase Pro/GDAX), Kraken, OKX (OKEx), Bybit, KuCoin, Gate/Gate.io, Bitfinex, Bitstamp, Gemini, Crypto.com, Huobi/HTX, MEXC. Case-insensitive. Anything else is dropped and reported in note - it does not fail the call.

There is no "all exchanges" mode. Omitting exchange segments gives you exactly the four defaults - it does not widen the query to every venue CoinGecko lists for the coin.

Exchanges requested ≠ prices returned. Each venue only contributes a price if it actually lists the coin against a USD-equivalent pair (USD/USDT/USDC). A thinly-listed altcoin can come back with 2 of 4 requested exchanges priced - each miss explained in note. Don't assume prices.length matches what you asked for; read it off the response.

URL-encode the whole {params} value as one unit (encodeURIComponent) - the | character is not safe unencoded in a URL path. ETH|Binance|Kraken goes on the wire as ETH%7CBinance%7CKraken.

Code samples

cURL

curl "https://api.gimmee.io/datagrab/finance/crypto/pricespread/BTC" \
  -H "x-api-key: YOUR_GIMMEE_KEY"

JavaScript (fetch)

const params = "ETH|Binance|Kraken"; // or just "BTC" for the four default exchanges
const response = await fetch(
  `https://api.gimmee.io/datagrab/finance/crypto/pricespread/${encodeURIComponent(params)}`,
  { headers: { "x-api-key": process.env.GIMMEE_API_KEY } }
);
const data = await response.json();
if (data.tradeSignal) {
  console.log(`${data.symbol}: buy ${data.lowestExchange}, sell ${data.highestExchange} (${data.spreadPercent}%)`);
}

Python (requests)

import os, requests
from urllib.parse import quote

params = "ETH|Binance|Kraken"  # or just "BTC" for the four default exchanges
response = requests.get(
    f"https://api.gimmee.io/datagrab/finance/crypto/pricespread/{quote(params, safe='')}",
    headers={"x-api-key": os.environ["GIMMEE_API_KEY"]}
)
data = response.json()

Response shape

JSON field names are camelCase.

{
  "symbol": "BTC",
  "name": "Bitcoin",
  "prices": [
    { "exchange": "Binance", "priceUsd": 64980.12, "quoteCurrency": "USDT" },
    { "exchange": "Coinbase Exchange", "priceUsd": 65310.47, "quoteCurrency": "USD" },
    { "exchange": "Kraken", "priceUsd": 65295.60, "quoteCurrency": "USD" },
    { "exchange": "OKX", "priceUsd": 65010.33, "quoteCurrency": "USDT" }
  ],
  "lowestExchange": "Binance",
  "highestExchange": "Coinbase Exchange",
  "spreadPercent": 0.5083,
  "signalTier": "signal",
  "tradeSignal": true,
  "note": "TRADE SIGNAL: 0.5083% spread on BTC — buy on Binance ($64980.12) and sell on Coinbase Exchange ($65310.47). Spread meets or exceeds the 0.5% threshold (excludes fees/withdrawal/slippage).",
  "timestampUtc": "2026-09-20T18:00:00Z",
  "dataProvidedBy": "Powered by CoinGecko (https://www.coingecko.com)",
  "termsOfServiceUrl": "https://www.coingecko.com/en/terms",
  "dataPullDateTime": "2026-09-20T18:00:00.1234567Z",
  "gimmeeVersion": "v1.0.0"
}

Error responses

Not an error, but check before trusting the result: an unrecognized coin symbol, an unrecognized exchange name, or an exchange that doesn't list the coin against a USD-equivalent pair all return 200 OK with an explanatory note - name empty for an unknown coin, or prices shorter than requested for a partial exchange miss. Always read note and signalTier rather than assuming a 200 means a full, priced result.

Integration notes

• Caching: prices are never cached - every call hits CoinGecko live, so you always get a current price. Symbol→coin-id resolution is cached inside the DataGrab (24h, in-memory), which speeds up repeat calls for the same symbol but doesn't change what price comes back. Cache the response client-side if you're polling on a fixed interval, to conserve your 1,000/mo quota.
• Gate on tradeSignal, not spreadPercent, for a conservative integration. tradeSignal is already true only when the spread clears the 0.50% threshold; recomputing that comparison yourself is exactly the step this field exists to save. Watch signalTier == "watch" too if you want near-opportunities surfaced before they cross the trade threshold.
• The spread is a raw price gap, not a net-profit estimate. It excludes exchange fees, withdrawal limits, slippage, and transfer time. Don't present tradeSignal as "guaranteed profitable" in end-user copy.
• prices.length can be less than what you asked for. A thinly-listed altcoin may only price on some of the requested exchanges; the rest are explained in note, not silently dropped.
• Attribution placement: required. CoinGecko's license requires the "Powered by CoinGecko" credit to be displayed to the end user wherever this data is shown (a clickable link to https://www.coingecko.com is preferred). This DataGrab emits it in dataProvidedBy; you must render it, not just store it.
• Symbol collisions: distinct coins can share a ticker. This DataGrab picks the highest-market-cap match for a given symbol, which is usually - but not guaranteed to be - what the caller means.
• Kraken lists Bitcoin and Dogecoin under its own legacy tickers (XBT, XDG), not BTC/DOGE - this is handled for you. You'll never see XBT/XDG in the response; this is called out only so you understand why Kraken's price for BTC or DOGE is correctly present even though Kraken's own trading UI shows those pair names.
• Error handling: a 502 is retryable (CoinGecko hiccup); a 400 means fix the request (missing symbol). Don't retry a 400.

Metadata (for the AI's own reference, not for display)

messageType: Finance.Crypto.Pricespread
status: production
price: paid, $19/mo
quota: 1000/month
lastVerified: 2026-09-20