Partner Exchange API

1. Overview

The Partner Exchange API lets you run crypto exchanges from your application with plain HTTP requests. You send JSON — the API returns the rate, a deposit address, and the exchange status. This section explains the overall flow; each step is covered in detail below.

How an exchange works

Every exchange follows the same four-step flow:

1. Catalog (GET /assets). Find out which assets are available and within what limits. The catalog provides the short asset codes — usdt, btc, eth, xmr, etc.
2. Quote (POST /quotes). You ask: "how much BTC will the client get for 20 USDT?" The API answers with the rate and exact amounts. A quote is non-binding and stays valid for 2 minutes.
3. Create exchange (POST /exchanges). You confirm the quote — the API opens an order and returns a deposit address the client must send funds to.
4. Status (GET /exchanges/{quote_id}). You poll the API to learn whether the deposit arrived and the payout was sent.

What you need to get started

1. A partner cabinet account.
2. An approved API access request (submitted in the cabinet, reviewed by an administrator).
3. An API key starting with spx_… — issued in the cabinet after approval. The key is shown only once when issued or reissued: store it somewhere safe right away.

Methods

Data format

• All requests and responses are JSON, UTF-8.
• All monetary amounts are strings: "20", "0.000312". The decimal separator is a dot. Strings are intentional: floating-point numbers lose precision on crypto amounts.
• Dates use ISO-8601 with a timezone, e.g. 2026-07-27T13:02:00+00:00.

Headers for every request

X-API-Key: spx_your_key
Content-Type: application/json   (POST requests only)
Accept: application/json

Key rules

• A quote is valid for 2 minutes (the expires_at field) — the exchange must be created before it expires.
• At most 1 request per IP address every 7 seconds across all methods; exceeding this returns HTTP 429 (see "Errors and limits").
• Retrying exchange creation with the same parameters is safe: no duplicate is created — the same exchange is returned.

2. Authentication

Every API request must include the X-API-Key header with your key. No tokens, signatures, or sessions — just this one header.

GET https://snapex.pro/api/v1/partner/assets
X-API-Key: spx_your_key
Accept: application/json

Where to get the key

Partner cabinet → "API" tab → "Issue key". The key starts with spx_ and is shown once. Reissuing immediately invalidates the old key.

Authentication errors

3. Asset catalog — GET /assets

The directory of available assets and send-amount limits. Integration starts here: it provides the asset codes for quotes and the allowed amount ranges. Success response — HTTP 200.

The API accepts only the short codes from the code field of this catalog (usdt, btc, eth, xmr, etc.). Raw internal blockchain identifiers are not accepted. The catalog changes rarely — you can cache it on your side for 5–10 minutes.

Request example

GET https://snapex.pro/api/v1/partner/assets
X-API-Key: spx_your_key
Accept: application/json

Response example

{
  "assets": [
    {
      "code": "usdt",
      "network": "TRON",
      "symbol": "USDT",
      "name": "USDT TRON",
      "min_amount": "10",
      "max_amount": "5000",
      "min_usd": "10",
      "max_usd": "5000"
    },
    {
      "code": "btc",
      "network": "Bitcoin",
      "symbol": "BTC",
      "name": "BTC",
      "min_amount": "0.000085",
      "max_amount": "0.0425",
      "min_usd": "10",
      "max_usd": "5000"
    }
  ]
}

Response fields

USD limits by route type

Limits depend on whether Monero (XMR) is part of the exchange. The check applies to the USD value of the amount the client sends.

Current catalog

The table below shows the same data GET /assets returns, for quick reference.

4. Quote — POST /quotes

Calculates the rate and exact exchange amounts. Creates nothing and commits you to nothing: no deposit address is allocated, no funds are reserved. Success response — HTTP 201. A quote is valid for 2 minutes.

Two modes: side=send and side=receive

The side parameter defines which of the two amounts is fixed:
side=send — "the client sends exactly X, how much will they get?" The amount is given in the send (from) asset.
side=receive — "the client wants to receive exactly Y, how much must they send?" The amount is given in the receive (to) asset.

Pass either amount or amount_usd — one of the two. Sending both returns a 422 error.

Request example

POST https://snapex.pro/api/v1/partner/quotes
Content-Type: application/json
X-API-Key: spx_your_key

{
  "from_asset_id": "usdt",
  "to_asset_id": "btc",
  "side": "send",
  "amount": "20",
  "recipient_address": "bc1qexampleaddress"
}

Request parameters

Response example

{
  "quote_id": "pq_abc123",
  "status": "quoted",
  "side": "send",
  "from_symbol": "USDT",
  "to_symbol": "BTC",
  "from_network": "TRON",
  "to_network": "Bitcoin",
  "request_amount": "20",
  "send_amount": "20",
  "receive_amount": "0.000312",
  "amount_in_usd": "20",
  "amount_out_usd": "19.85",
  "expires_at": "2026-07-27T13:02:00+00:00"
}

Response fields

5. Create exchange — POST /exchanges

Turns a quote into a real exchange: an order is opened and a deposit address is returned for the client transfer. Call it before the quote expires (2 minutes). Success response — HTTP 201.

Request example

POST https://snapex.pro/api/v1/partner/exchanges
Content-Type: application/json
X-API-Key: spx_your_key

{
  "quote_id": "pq_abc123",
  "recipient_address": "bc1qexampleaddress"
}

Request parameters

What happens on this call

1. The API finds your quote and checks it has not expired.
2. The rate is re-checked against the market. If it moved against the quote by more than 2%, no exchange is created and 422 is returned (simply request a new quote).
3. An order is opened and a deposit address is allocated.
4. The response includes the deposit block — the address and amount the client must transfer.

Response example

{
  "quote_id": "pq_abc123",
  "status": "awaiting_deposit",
  "side": "send",
  "from_symbol": "USDT",
  "to_symbol": "BTC",
  "from_network": "TRON",
  "to_network": "Bitcoin",
  "request_amount": "20",
  "send_amount": "20",
  "receive_amount": "0.000312",
  "amount_in_usd": "20",
  "amount_out_usd": "19.85",
  "expires_at": "2026-07-27T13:02:00+00:00",
  "deposit": {
    "asset": "USDT",
    "amount": "20",
    "address": "TXyz…",
    "amount_usd": "20"
  },
  "exchange": {
    "public_id": "ex_…",
    "status": "awaiting_deposit",
    "recipient_address": "bc1qexampleaddress"
  }
}

New fields compared to the quote

Retries (idempotency)

If the connection dropped and you never got a response — just repeat the request with the same quote_id and recipient_address. No duplicate is created: the API returns the already existing exchange. The recipient_address cannot be changed after creation — attempting to do so returns 422.

Possible errors

• 409 quote_expired — the quote expired (more than 2 minutes passed). Request a new one via POST /quotes.
• 422 validation_error — invalid parameters; an attempt to change recipient_address on retry; or the rate moved by more than 2% — request a new quote.
• 404 not_found — the quote_id does not exist or belongs to another partner.
• 503 upstream_unavailable — temporary liquidity provider failure. Retry later with the same quote (if still valid) or a new one.

6. Status — GET /exchanges/{quote_id}

Returns the current state of a quote or exchange. The response format is identical to the create response. Success response — HTTP 200. Poll at most once every 7 seconds.

Request example

GET https://snapex.pro/api/v1/partner/exchanges/pq_abc123
X-API-Key: spx_your_key
Accept: application/json

status values

Terminal statuses: completed, error, cancelled, expired. The state no longer changes after them — further polling is unnecessary.

When status=completed, the exchange block may include partner_api_earning_usd — your earnings on the deal in USD.

Response example

{
  "quote_id": "pq_abc123",
  "status": "completed",
  "side": "send",
  "from_symbol": "USDT",
  "to_symbol": "BTC",
  "from_network": "TRON",
  "to_network": "Bitcoin",
  "request_amount": "20",
  "send_amount": "20",
  "receive_amount": "0.000312",
  "amount_in_usd": "20",
  "amount_out_usd": "19.85",
  "expires_at": "2026-07-27T13:02:00+00:00",
  "deposit": {
    "asset": "USDT",
    "amount": "20",
    "address": "TXyz…",
    "amount_usd": "20"
  },
  "exchange": {
    "public_id": "ex_…",
    "status": "completed",
    "recipient_address": "bc1qexampleaddress",
    "partner_api_earning_usd": "0.20"
  }
}

7. Errors and limits

All errors share a single JSON format. The HTTP status code mirrors the meaning of the error field — rely on either one.

{
  "ok": false,
  "error": "validation_error",
  "message": "Human-readable explanation in English"
}

Error reference

Rate limits

8. Example: an exchange from start to finish

Full scenario: the client sends 20 USDT (TRON network) and receives BTC at their Bitcoin address. Replace YOUR_KEY with your API key.

Step 1. Request a quote

curl -sS -X POST 'https://snapex.pro/api/v1/partner/quotes' \
  -H 'X-API-Key: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "from_asset_id": "usdt",
    "to_asset_id": "btc",
    "side": "send",
    "amount": "20",
    "recipient_address": "bc1qexample"
  }'

The response contains a quote_id (pq_…) and the amounts. Show the client receive_amount — that is how much BTC they will get. You have 2 minutes for the next step.

Step 2. Create the exchange

curl -sS -X POST 'https://snapex.pro/api/v1/partner/exchanges' \
  -H 'X-API-Key: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "quote_id": "pq_FROM_STEP_1",
    "recipient_address": "bc1qexample"
  }'

The response now includes the deposit block with an address and amount. Show the client deposit.address and deposit.amount — they must transfer exactly that amount to that address.

Step 3. Track the status

curl -sS 'https://snapex.pro/api/v1/partner/exchanges/pq_FROM_STEP_1' \
  -H 'X-API-Key: YOUR_KEY' \
  -H 'Accept: application/json'

Repeat the request with a 7–10 second pause. Once the client transfers the funds, the status changes to processing, then to completed — the payout has been sent. Terminal statuses: completed, error, cancelled, expired.

The same scenario in Python

import time
import requests

API = "https://snapex.pro/api/v1/partner"
HEADERS = {
    "X-API-Key": "YOUR_KEY",
    "Content-Type": "application/json",
    "Accept": "application/json",
}

# Step 1. Quote: the client sends 20 USDT, receives BTC
quote = requests.post(f"{API}/quotes", headers=HEADERS, json={
    "from_asset_id": "usdt",
    "to_asset_id": "btc",
    "side": "send",
    "amount": "20",
    "recipient_address": "bc1qexample",
}).json()
print("Client receives:", quote["receive_amount"], quote["to_symbol"])

# Step 2. Create the exchange (within 2 minutes of the quote)
exchange = requests.post(f"{API}/exchanges", headers=HEADERS, json={
    "quote_id": quote["quote_id"],
    "recipient_address": "bc1qexample",
}).json()
deposit = exchange["deposit"]
print("Client must transfer:", deposit["amount"], deposit["asset"])
print("To address:", deposit["address"])

# Step 3. Poll the status until terminal
while True:
    time.sleep(10)  # at most 1 request every 7 seconds
    state = requests.get(
        f"{API}/exchanges/{quote['quote_id']}", headers=HEADERS
    ).json()
    print("Status:", state["status"])
    if state["status"] in ("completed", "error", "cancelled", "expired"):
        break

Common beginner mistakes

• Sending the amount as a number instead of a string. Correct: "amount": "20", not "amount": 20.
• With side=receive, giving the amount in the send asset. For receive, amount is in the receive (to) asset.
• Creating the exchange more than 2 minutes after the quote — you get 409 quote_expired. Request the quote right before creating.
• Sending requests more often than once every 7 seconds — you get 429. Add a pause between requests.