API documentation

Bring exchange to your product: get a quote, create an order and track execution. API methods, examples and integration steps in one place.

Start

Create a key in your account and include it in the header of each request.

Base URL

https://co-re.io

Integration sequence

  1. Keep the key on your server. Use the embed widget if you do not need a custom exchange interface. Configure widget
  2. Load the currency catalogue, check networks and limits, then request a quote.
  3. Collect payout and refund addresses and any memo they need: memo for the payout, refundMemo for the refund. If the refund address belongs to an exchange or custodial service, a refund without the memo is lost - always send refundMemo in that case. Create the exchange with a unique Idempotency-Key.
  4. Show deposit instructions only for stage AWAITING_DEPOSIT. Wait for review on UNDER_REVIEW. Give the client the trackUrl and poll the status.

Open partner dashboard

Keys

The key goes in the Authorization header as a Bearer token and is shown once. Create your first key in your account; contact CORE support for additional keys or replacements, even after revocation. You can revoke a key yourself. There is no sandbox: a key is live from the first minute.

curl https://co-re.io/api/v1/quotes \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"send":{"asset":"BTC","network":"BTC"},
       "receive":{"asset":"USDT","network":"TRON"},
       "amount":"0.05"}'

Per key: 600 requests per minute for reads - catalogue, limits, address checks, quotes and deal reads. GET /pairs: 30 per minute. Creating exchanges and /balance: 60 per minute, counted separately, so polling rates never eats into creating. A /quotes/bulk call costs 1 + ceil(n/5) read requests, one bulk at a time. Need more? Ask us: a key's limit can be raised, and both counts grow in the same ratio. Polling every open deal every 15-30 seconds counts against the read limit. One IP may send 120 requests per minute with an unknown or revoked key; successful requests do not count. A 429 carries Retry-After: the seconds to wait.

Conventions

Amounts are decimal strings, for example "0.0213585". Do not convert them to floating-point numbers: this loses precision.

Specify both the asset code and network. USDT on TRON and USDT on Ethereum require different addresses and are not interchangeable.

Use code to handle the error and message to inform the user.

{ "error": { "code": "pair_unavailable", "message": "..." } }

Times are UTC, ISO 8601.

Currency catalogue

GET/api/v1/currencies

What CORE can exchange right now: code, network, which direction works, whether a memo is required, and the precision. For mapping your own coin list: the contract address, the EVM chainId, what the network calls the memo, the explorer transaction URL (replace {txHash}) and an icon. contractAddress is set only where we verified it against the chain; null means a native coin or an address we do not have. It asks no executor, so it is cheap and cacheable. On a memo network sendEnabled is true only when an executor accepts a memo for the refund address (refundMemo on POST /deals).

Access: Live key.

Response 200

{
  "currencies": [
    {
      "asset": "USDT",
      "network": "ETH",
      "name": "Tether USD",
      "networkName": "Ethereum",
      "sendEnabled": true,
      "receiveEnabled": true,
      "memoRequired": false,
      "decimals": 6,
      "memoName": null,
      "contractAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "chainId": 1,
      "explorerTxUrl": "https://etherscan.io/tx/{txHash}",
      "iconUrl": "https://co-re.io/coins/usdt.svg"
    },
    {
      "asset": "XRP",
      "network": "XRP",
      "name": "XRP",
      "networkName": "XRP Ledger",
      "sendEnabled": true,
      "receiveEnabled": true,
      "memoRequired": true,
      "decimals": 6,
      "memoName": "Destination tag",
      "contractAddress": null,
      "chainId": null,
      "explorerTxUrl": "https://xrpscan.com/tx/{txHash}",
      "iconUrl": "https://co-re.io/coins/xrp.svg"
    }
  ],
  "count": 2
}

Can return

401 unauthorized403 ip_not_allowed503 service_unavailable429 rate_limited500 internal_error

Exchange pairs

GET/api/v1/pairs

Every direction CORE can quote right now: asset and network on both sides, with the stored minimum. It asks no provider: the list is built from the same catalogue the quote path uses and kept in memory for 5 minutes, so the call is cheap. Its own limit: 30 calls per minute per key. The answer carries ETag and Cache-Control: send If-None-Match and an unchanged list comes back as 304 with no body. The filter ?send=ASSET:NETWORK (for example BTC:BTC) keeps the directions from one asset. min is the lowest minimum any executor stated, in the send asset; null when it was not measured in the last 12 hours. max is always null for now: /limits gives the live band. The quote stays the authority: a listed pair can still be refused by the executors. One direction is about 110 bytes and the unfiltered answer carries every direction at once, so ask for compression (Accept-Encoding: gzip) or use the filter. A memo network is a send side only where an executor that accepts a memo for the refund address serves the direction (as sendEnabled on /currencies). If the refund address belongs to an exchange or custodial service, send refundMemo on POST /deals for such a direction: a refund without the memo is lost.

Access: Live key.

Response 200

{
  "pairs": [
    {
      "send":    { "asset": "BTC",  "network": "BTC" },
      "receive": { "asset": "USDT", "network": "TRON" },
      "min": "0.0007",
      "max": null
    },
    {
      "send":    { "asset": "BTC", "network": "BTC" },
      "receive": { "asset": "XRP", "network": "XRP" },
      "min": null,
      "max": null
    }
  ],
  "count": 2,
  "updatedAt": "2026-09-30T09:14:44.000Z"
}

Can return

400 invalid_request401 unauthorized403 ip_not_allowed503 service_unavailable429 rate_limited500 internal_error

Amount band

POST/api/v1/limits

The minimum and maximum for a pair, both denominated in the send asset. Derived by asking providers with two deliberately out-of-range amounts, so it costs two provider round-trips; a complete answer for a pair is kept for 5 minutes. Cache it per pair, do not call it per keystroke; GET /pairs has the minimum of every pair at once. null means no provider stated one - not zero, and not unlimited.

Access: Live key.

Request

{
  "send":    { "asset": "BTC",  "network": "BTC" },
  "receive": { "asset": "USDT", "network": "TRON" }
}

Response 200

{
  "limits": {
    "send":    { "asset": "BTC",  "network": "BTC" },
    "receive": { "asset": "USDT", "network": "TRON" },
    "min": "0.0007",
    "max": null
  }
}

Can return

400 invalid_request401 unauthorized403 ip_not_allowed503 service_unavailable422 pair_unavailable429 rate_limited500 internal_error

Validate an address

POST/api/v1/validate-address

The same question create will ask, from the same module - validate first and create will not then refuse the address. It also answers the memo question, which is the one that loses coins: an XRP payout without its tag is unrecoverable, and knowing that before the form is submitted is worth more than knowing it after. Structural only: shape, charset, length. Not a checksum, and not whether anybody controls it.

Access: Live key.

Request

{
  "asset":   "XRP",
  "network": "XRP",
  "address": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH"
}

Response 200

{
  "valid": true,
  "networkKnown": true,
  "memoRequired": true,
  "checked": "structure"
}

Can return

400 invalid_request401 unauthorized403 ip_not_allowed503 service_unavailable429 rate_limited500 internal_error

Commission balance

GET/api/v1/balance

Rewards in USD. pending is the reward on completed swaps whose income is not confirmed yet; it cannot be withdrawn. On confirmation it moves to available. available accounts for holds, reservations and recoveries. held means the funding source needs review. Read the withdrawal minimum from balance.minPayout. monthVolume is the volume counted towards your share this calendar month (UTC), in USD; your share grows with it. toNextLevel is the counted volume this month still needed to raise your share, null at the top level. Both are null when there is nothing to show; the money fields are unaffected.

Access: Live key.

Response 200

{
  "balance": {
    "currency": "USD",
    "available": "0",
    "pending": "0",
    "held": "0",
    "reserved": "0",
    "paid": "0",
    "minPayout": "100",
    "monthVolume": "3120.45",
    "toNextLevel": "11879.55"
  }
}

Can return

401 unauthorized403 ip_not_allowed503 service_unavailable503 balance_unavailable429 rate_limited500 internal_error

Quote

POST/api/v1/quotes

The best live rate for a pair and amount across active providers. Creates nothing and moves nothing. The executor is named where its own terms require it, and marked undisclosed otherwise. Floating rate and send amount only, as on /deals: rateType and amountSide may be omitted, and any other value returns unsupported_option. min and max are the pair's stored band, the same as GET /pairs, in the send asset; null means not known here - not zero and not unlimited. When the send network needs a memo, the rate is compared only among executors that accept a memo for the refund address: the same ones POST /deals routes to.

Access: Live key.

Request

{
  "send":    { "asset": "BTC",  "network": "BTC" },
  "receive": { "asset": "USDT", "network": "TRON" },
  "amount":  "0.05"
}

Response 200

{
  "quote": {
    "send":    { "asset": "BTC",  "network": "BTC",  "amount": "0.05" },
    "receive": { "asset": "USDT", "network": "TRON", "amount": "3212.44" },
    "rateType": "float",
    "expiresAt": "2026-08-24T09:14:44Z",
    "executor": { "disclosed": false, "executorTermsAccepted": true },
    "coreMarkup": "0",
    "partnerMarkup": "0",
    "comparedExecutors": 3,
    "min": "0.0007",
    "max": null
  }
}

What you can show your own users

The /quotes response carries executor: by default only the fact that there is one and that its terms are accepted. The name, disclosure and passport (who holds the deposit, rate modes, terms, and our own history with that provider) come back where the executor's terms require naming it. comparedExecutors is a count by default: how many executors answered. Whether you show any of it to your own user is your decision, not our requirement. The executor names are switched on per key, for a partner that really does show the comparison.

Completed exchanges made with your key can earn a reward. Where the executor withholds a markup on the order, the reward for that exchange is the markup. An amount stays pending until the income is confirmed, then it can be withdrawn. Earnings and payouts are shown in your partner account and at /api/v1/balance. partnerMarkup is always the string "0" and does not show earnings.

Can return

400 invalid_request400 invalid_amount422 unsupported_option401 unauthorized403 ip_not_allowed503 service_unavailable422 amount_below_minimum422 amount_above_maximum422 pair_unavailable503 pricing_unavailable429 rate_limited500 internal_error

Bulk quotes

POST/api/v1/quotes/bulk

Up to 20 quotes in one call, for rate tables across many pairs. Each item is computed exactly as POST /quotes and answered with the same body: quote or error, plus status - the HTTP status a single request would have got. Results come in item order; index is the item's position. A bad item never fails the batch: its error is in its own result. Items run in parallel; the batch takes at most 8 seconds and late items get quote_timeout. Costs 1 + ceil(n/5) read requests: 20 items cost 5. A key runs one bulk at a time: a second one while the first is running gets 429 with Retry-After. The errors listed below are errors of the whole request.

Access: Live key.

Request

{
  "items": [
    {
      "send":    { "asset": "BTC",  "network": "BTC" },
      "receive": { "asset": "USDT", "network": "TRON" },
      "amount":  "0.05"
    },
    {
      "send":    { "asset": "ETH",  "network": "ETH" },
      "receive": { "asset": "USDT", "network": "TRON" },
      "amount":  "0.0001"
    }
  ]
}

Response 200

{
  "results": [
    {
      "index": 0,
      "status": 200,
      "quote": {
        "send":    { "asset": "BTC",  "network": "BTC",  "amount": "0.05" },
        "receive": { "asset": "USDT", "network": "TRON", "amount": "3212.44" },
        "rateType": "float",
        "expiresAt": "2026-08-24T09:14:44Z",
        "executor": { "disclosed": false, "executorTermsAccepted": true },
        "coreMarkup": "0",
        "partnerMarkup": "0",
        "comparedExecutors": 3,
        "min": "0.0007",
        "max": null
      }
    },
    {
      "index": 1,
      "status": 422,
      "error": {
        "code": "amount_below_minimum",
        "message": "The amount is below the minimum for this pair. The minimum is 0.004 ETH/ETH."
      }
    }
  ],
  "count": 2
}

Can return

400 invalid_request401 unauthorized403 ip_not_allowed503 service_unavailable503 pricing_unavailable429 rate_limited500 internal_error

Deal list

GET/api/v1/deals

Your deals, newest first. Parameters: limit (default 50, maximum 100) and cursor from the previous page's nextCursor. partnerMarkup is the partner markup stored on this deal's quote, as recorded; it is "0" wherever the markup was off, and it does not establish earnings. commissionUsd is the posted USD accrual. null means no accrual has posted, including for a completed swap awaiting income evidence. It does not mean zero earnings. Use /balance for the withdrawable amount.

Access: Live key. Only deals your key created are visible.

Response 200

{
  "deals": [
    {
      "id": "7f1c...",
      "status": "COMPLETED",
      "stage": "COMPLETED",
      "createdAt": "2026-08-24T09:12:44Z",
      "send":    { "asset": "BTC",  "network": "BTC",  "amount": "0.05" },
      "receive": { "asset": "USDT", "network": "TRON", "amount": "3180.31", "final": true },
      "partnerMarkup": "0",
      "commissionUsd": null
    }
  ],
  "nextCursor": "MjAyNi0wOC0yNFQwOToxMjo0NFp8N2YxYw"
}

Can return

400 invalid_request401 unauthorized403 ip_not_allowed503 service_unavailable429 rate_limited500 internal_error

Create an exchange

POST/api/v1/deals

Picks the executor, re-quotes with it and returns the deposit address your client pays into. A rate from /quotes is never accepted: it is always recomputed. Floating rate and send amount only: rateType and amountSide may be omitted, and any other value returns unsupported_option. memo is a string; a whole number (an XRP tag) is accepted too. refundMemo is the memo of the refund address, same rules; when the send network needs a memo or refundMemo is sent, the exchange goes only to an executor that accepts a refund memo. If the refund address belongs to an exchange or custodial service, a refund without the memo is lost - always send refundMemo in that case. A retry with the same Idempotency-Key is answered from the recorded deal without a new quote, so it does not depend on whether the pair is available right now. status and stage in the response are the ones GET /deals/:id returns: ACTIVE and AWAITING_DEPOSIT for a new exchange.

Access: Live key only. An Idempotency-Key header is required.

Request

{
  "send":          { "asset": "BTC",  "network": "BTC" },
  "receive":       { "asset": "USDT", "network": "TRON" },
  "amount":        "0.05",
  "payoutAddress": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "refundAddress": "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4",
  "refundMemo":    null,
  "memo":          null,
  "campaignId":    null
}

Response 201

{
  "deal": {
    "id": "7f1c...",
    "status": "ACTIVE",
    "stage": "AWAITING_DEPOSIT",
    "send":    { "asset": "BTC",  "network": "BTC",  "amount": "0.05" },
    "receive": { "asset": "USDT", "network": "TRON", "amount": "3212.44" },
    "deposit": {
      "address":  "bc1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3qccfmv3",
      "tag":      null,
      "amount":   "0.05",
      "deadline": "2026-07-27T10:15:00Z"
    },
    "trackUrl": "https://<site>/track/7f1c..."
  }
}
202: under review, do not send a deposit

If creation is unconfirmed, the API returns 202 with status ACTIVE, stage UNDER_REVIEW and no deposit address. This is not confirmation that the exchange was created. Do not request a deposit from the customer; an operator will review the order.

Can return

400 invalid_request400 invalid_amount400 idempotency_key_required409 idempotency_key_conflict503 pricing_unavailable503 service_unavailable503 quote_unavailable503 replay_executor_unavailable503 order_reservation_failed422 executor_refused_request401 unauthorized403 ip_not_allowed422 amount_below_minimum422 amount_above_maximum422 pair_unavailable422 invalid_payout_address422 invalid_refund_address422 invalid_campaign422 memo_required422 refund_memo_unsupported422 unsupported_option429 rate_limited500 internal_error

Status

GET/api/v1/deals/:id

The current state of your deal, reconstructed from the event log. status is the deal status, stage the exchange step (tables below). Reading is not passive: while the deal runs, CORE asks the executor for a fresh status and advances the deal before answering, so a GET can return a newer status than the one before it (at most six times a minute per deal). While the deposit is awaited the response repeats the deposit details.

Access: Live key only. Only deals your key created are visible.

Response 200

{
  "deal": {
    "id": "7f1c...",
    "status": "ACTIVE",
    "stage": "AWAITING_DEPOSIT",
    "send":    { "asset": "BTC",  "network": "BTC",  "amount": "0.05" },
    "receive": { "asset": "USDT", "network": "TRON", "amount": "3212.44", "final": false },
    "deposit": {
      "address": "bc1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3qccfmv3",
      "tag": null,
      "amount": "0.05",
      "deadline": "2026-08-24T09:42:44Z"
    },
    "trackUrl": "https://<site>/track/7f1c..."
  }
}

The trackUrl in a response is the public deal page. You can hand it to your client: no account is needed, and it shows the status, the hashes and a support form.

Can return

401 unauthorized403 ip_not_allowed503 service_unavailable404 not_found429 rate_limited500 internal_error

Deal statuses

status is the deal status: whether the deal is running and how it ended. Create, GET, the list and webhooks all return the same value.

DRAFTRecorded; the provider order is not confirmed yet.
ACTIVEIn flight: awaiting the deposit, confirmations, the exchange or the payout.
COMPLETEDThe payout has been sent to the client. · terminal
FAILEDThe exchange did not happen and no refund was made. · terminal
REFUNDEDThe provider returned the coins to the refund address. · terminal
EXPIREDThe deposit did not arrive in time. · terminal

Exchange step

stage is the step inside the deal, and the one to show your client. It comes next to status wherever a deal does.

AWAITING_DEPOSITWaiting for the deposit. The details are in deposit.
CONFIRMINGThe deposit is seen; the network is confirming it.
EXCHANGINGThe deposit is confirmed; the exchange is running.
SENDINGThe payout is being sent to the client.
COMPLETEDThe payout has been sent. · terminal
FAILEDThe exchange did not happen. · terminal
REFUNDEDThe deposit went back to the refund address. · terminal
EXPIREDThe deposit did not arrive in time. · terminal
ACTION_REQUIREDThe exchange is paused on a problem with the deposit or the order, for example an underpayment. Support resolves it with the client; send the client to trackUrl.
UNDER_REVIEWThe executor order is not confirmed and there is no deposit address. Send nothing: an operator is checking it.

Status and step changes arrive by webhook when one is set up: deal.status_changed and deal.stage_changed. GET /api/v1/deals/:id is the source of truth: without a webhook, poll it every 15-30 seconds and stop on a terminal status.

Webhooks

A webhook is set per API key in your account: one https address on port 443 per key. Saving it shows the signing secret, once. The same place sends a test event, issues a new secret and lists recent deliveries with their response code. Get a key

Events

deal.status_changed A deal created with this key moved to another status. previousStatus and status describe that transition. deal is the same object GET /api/v1/deals/:id returns, stage included, as of the first delivery attempt. Steps within ACTIVE arrive as deal.stage_changed.

{
  "id": "0b6c3a1e-5d2f-4c8a-9e61-2f4b7d9c1a30",
  "type": "deal.status_changed",
  "createdAt": "2026-08-24T09:40:02.113Z",
  "data": {
    "previousStatus": "ACTIVE",
    "status": "COMPLETED",
    "deal": {
      "id": "7f1c...",
      "status": "COMPLETED",
      "stage": "COMPLETED",
      "trackUrl": "https://<site>/track/7f1c...",
      "send":    { "asset": "BTC",  "network": "BTC",  "amount": "0.05" },
      "receive": { "asset": "USDT", "network": "TRON", "amount": "3180.31", "final": true }
    }
  }
}

deal.stage_changed The stage of a deal created with this key changed: the deposit is seen, the exchange is running, the payout is being sent, and so on. previousStage and stage describe that step. One change is one event; transitions that do not change the stage send none. deal is the same object GET /api/v1/deals/:id returns, as of the first delivery attempt. The final step arrives both as this event and as deal.status_changed. Two stage changes made in one transaction can arrive in either order: rely on previousStage, or confirm with GET.

{
  "id": "4d2a7c90-1b3e-4f5a-8c6d-7e8f9a0b1c2d",
  "type": "deal.stage_changed",
  "createdAt": "2026-08-24T09:21:37.540Z",
  "data": {
    "previousStage": "AWAITING_DEPOSIT",
    "stage": "CONFIRMING",
    "deal": {
      "id": "7f1c...",
      "status": "ACTIVE",
      "stage": "CONFIRMING",
      "trackUrl": "https://<site>/track/7f1c...",
      "send":    { "asset": "BTC",  "network": "BTC",  "amount": "0.05" },
      "receive": { "asset": "USDT", "network": "TRON", "amount": "3212.44", "final": false }
    }
  }
}

reward.available An accrual on your account became withdrawable. The amount in USD only: the event carries no rate. Sent to every webhook of the account. The amount in the example is illustrative.

{
  "id": "5e0a9d44-7b1c-4f3e-8a26-c91d0f6b2e77",
  "type": "reward.available",
  "createdAt": "2026-08-31T00:01:10.502Z",
  "data": {
    "reward": { "id": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "amount": "1.25", "currency": "USD" }
  }
}

webhook.test Sent from the button in your account. Signed exactly like real events.

{
  "id": "9a7e2c11-3f64-4d0b-b5a8-0e2c6f1d4b93",
  "type": "webhook.test",
  "createdAt": "2026-08-24T09:12:44.000Z",
  "data": {}
}

Signature

Every request carries X-Core-Signature: t=<unix seconds>,v1=<hex>. v1 is the HMAC-SHA256 of the string "t.body" with your secret. Verify it against the raw request body before parsing JSON, and reject a t older than 300 seconds.

Node.js

const crypto = require("node:crypto");

// rawBody: the request body exactly as received, before any JSON parsing.
function verifyCoreWebhook(rawBody, header, secret, toleranceSeconds = 300) {
  if (typeof header !== "string" || header === "") return false;
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp) || !/^[0-9a-f]{64}$/.test(parts.v1 ?? "")) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest();
  return crypto.timingSafeEqual(Buffer.from(parts.v1, "hex"), expected);
}

Python

import hashlib, hmac, re, time

# raw_body: the request body bytes exactly as received, before any JSON parsing.
def verify_core_webhook(raw_body: bytes, header, secret: str, tolerance: int = 300) -> bool:
    if not isinstance(header, str) or not header:
        return False
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not re.fullmatch(r"[0-9]{1,12}", t) or not re.fullmatch(r"[0-9a-f]{64}", v1):
        return False
    if abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

PHP

<?php
// $rawBody = file_get_contents('php://input');
// $header  = $_SERVER['HTTP_X_CORE_SIGNATURE'] ?? '';
function verifyCoreWebhook(string $rawBody, string $header, string $secret, int $tolerance = 300): bool {
    $parts = [];
    foreach (explode(',', $header) as $pair) {
        [$key, $value] = array_pad(explode('=', $pair, 2), 2, '');
        $parts[$key] = $value;
    }
    $t = $parts['t'] ?? '';
    $v1 = $parts['v1'] ?? '';
    if (!preg_match('/^[0-9]{1,12}$/', $t) || !preg_match('/^[0-9a-f]{64}$/', $v1)) {
        return false;
    }
    if (abs(time() - (int) $t) > $tolerance) {
        return false;
    }
    $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    return hash_equals($expected, $v1);
}

Delivery

Delivered means any 2xx within 5 seconds. Redirects are not followed and count as a failure. Retries after: 30 s, 2 min, 10 min, 30 min, 1 h, 3 h, 6 h, 12 h, then delivery stops. One event can arrive more than once and out of order: keep the ids you processed (the same value as the X-Core-Event-Id header, one per webhook and unchanged on retries) and confirm the status with GET. The address must be public: nothing is sent to private networks or metadata addresses.

Idempotency

Idempotency-Key is required when creating an exchange. Without it, the API returns 400. A retry with the same key returns the original deal without creating another or quoting again, so the answer does not depend on whether the pair is available right now.

curl https://co-re.io/api/v1/deals \
  -H "Authorization: Bearer <api_key>" \
  -H "Idempotency-Key: 6b1f2c58-0a1e-4b3f-9d21-8c0f4a7e5b12" \
  -H "Content-Type: application/json" \
  -d '{"send":{"asset":"BTC","network":"BTC"},
       "receive":{"asset":"USDT","network":"TRON"},
       "amount":"0.05",
       "payoutAddress":"TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
       "refundAddress":"bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4"}'

Generate the key per exchange attempt, not per HTTP request. Retry with the same key until you get a final answer. Format: 8 to 128 characters, ASCII letters, digits and . _ : - , starting with a letter or digit; a UUID works.

Errors

HTTPcode
400invalid_requestThe body is not JSON; a required field is missing (send, receive, amount, payoutAddress, refundAddress, or asset, network, address on /validate-address); memo or refundMemo is neither a string nor a non-negative whole number, or refundMemo is longer than 256 characters; a refundMemo on a send network with no memo; the Idempotency-Key is malformed (8 to 128 characters: ASCII letters, digits and . _ : -, starting with a letter or digit); limit or cursor on GET /deals is invalid; send on GET /pairs is not ASSET:NETWORK; or items on /quotes/bulk is not an array of 1 to 20. On /quotes/bulk a bad item gets this in its own result, not the whole request.
400invalid_amountamount is not a positive decimal string.
400idempotency_key_requiredPOST /deals came without an Idempotency-Key header. Without it a retry would create a second exchange.
401unauthorizedNo Authorization header, or the key is invalid or revoked.
403ip_not_allowedThe key has an IP allowlist and the request came from another address. Change the list in the cabinet, API section.
404not_foundNo deal with that id among the ones your key created. Another tenant's deal also returns 404: existence is not leaked. Also returned for an /api/v1/... path that does not exist.
405method_not_allowedThe method does not apply to the endpoint, for example DELETE /api/v1/quotes. The Allow header lists the ones that do.
409idempotency_key_conflictThe same Idempotency-Key against a different exchange: another pair, amount or address, including a different refundAddress or refundMemo. Generate one key per exchange attempt and reuse it only for retries of that attempt. Since migration 085 this no longer fires merely because the comparison routed elsewhere on the retry.
503pricing_unavailableFee settings could not be verified. An exchange is not created with an unverified fee. Retry shortly; keep the same Idempotency-Key when creating a deal.
503service_unavailableA read of our own records failed: the API key on any request, the asset registry on /validate-address, or the asset registry, the campaign or an existing order on POST /deals. Nothing new was created, and it does not count towards the failed-attempts limit of your IP. Retry shortly; keep the same Idempotency-Key when creating a deal.
503quote_timeoutOnly in a /quotes/bulk item: the executors did not answer for this item within 8 seconds. The other items are unaffected. Retry this item.
503quote_unavailableThe selected quote could not be refreshed before creating the exchange. No create request was sent to the provider. Retry with the same Idempotency-Key.
503replay_executor_unavailableA retry with the same Idempotency-Key: the exchange already exists, but the executor holding it cannot be reached right now. Retry with the SAME key shortly. A new key would create a second real order.
503order_reservation_failedThe exchange could not be confirmed. Retry with the SAME key: a retry never creates a second order. If an order was created at the provider after all, the retry returns it or the exchange goes to operator review.
422executor_refused_requestThe executor validated the request and refused it: a bad address, an amount out of range, an unsupported asset, or an expired quote. No order exists and no deposit is needed. Correct it and submit with a NEW Idempotency-Key. This used to return a 202 under review telling you to hold a deposit for an order that was never coming.
422unsupported_optionA request to /quotes or /deals explicitly asks for something the API does not offer: rateType (rate_type) other than "float", or amountSide (amount_side) other than "SOURCE". Fixed rates and exact receive amounts are not supported. Such fields used to be ignored silently: /deals created a floating-rate exchange and /quotes returned a floating rate.
422amount_below_minimumThe amount is below the provider minimum for this pair. Increase it.
422amount_above_maximumThe amount is above the provider maximum for this pair. Reduce it. This case used to arrive as pair_unavailable, which was false.
422pair_unavailableNo active provider quotes this pair right now, or the instrument was disabled between the quote and the create.
422invalid_payout_addresspayoutAddress does not look like an address on the receive network. Checked before any provider call.
422invalid_campaigncampaignId is not an active campaign of your account. Checked before any provider call.
422invalid_refund_addressrefundAddress does not look like an address on the send network.
422memo_requiredThe receive network requires a memo or tag and the memo field was not sent.
422refund_memo_unsupportedThe send network identifies the beneficiary by memo, or a refundMemo was sent, and no executor for this pair accepts a memo for the refund address right now. Or the executor chosen for the exchange stopped accepting a refund memo before the order was placed: no order was created, submit it again with a NEW Idempotency-Key.
503balance_unavailableThe balance cannot be read right now. An error, not a zero: a false zero on a money endpoint is worse than a 5xx.
429rate_limitedThe key went over a limit: 600 requests per minute for reads (catalogue, limits, address checks, quotes, deal reads), 30 for GET /pairs, or 60 for creating exchanges and /balance, unless a higher limit was agreed for the key. A /quotes/bulk call costs 1 + ceil(n/5) read requests, and a key runs one bulk at a time: a second one while the first is running gets 429. Or one IP sent more than 120 requests in a minute with an unknown or revoked key, or from an address the key does not allow; successful requests do not count. The Retry-After header says how many seconds to wait.
500internal_errorAn unexpected error on our side; it is logged. Retry the same request (on POST /deals, with the same Idempotency-Key): a retry never creates a second exchange.

What the API does not do

Not supported: fixed rates, cancelling a created exchange, specifying an exact receive amount, separate network-fee breakdowns or a sandbox. Active providers use floating rates.

Countries and territories

CORE does not serve clients from the following countries and territories: North Korea, Iran, Syria, Cuba, Myanmar, Crimea, Sevastopol, Donetsk region, Luhansk region, United States, Puerto Rico, Guam, U.S. Virgin Islands, American Samoa, Northern Mariana Islands, U.S. Minor Outlying Islands, United Kingdom, Canada, Japan. The API does not check the country by request IP: requests come from your server. Do not create exchanges for users from these countries and territories.