GET /v1/deposit-requests/{request_id}

Returns the current status of a deposit request (created via POST /v1/deposit-addresses) along with every on-chain transaction observed against the allocated address. Integrators poll this endpoint to follow a deposit from detected through confirmed.

Method & path	GET /v1/deposit-requests/{request_id}
Required permission	read_deposit_status
Auth	HMAC — see Authentication

Path parameters

Name	Type	Required	Description
request_id	integer	required	The request_id returned by POST /v1/deposit-addresses.

Cross-account requests return 404 — another integrator's request_id simply doesn't resolve.

Response

{
  "success": true,
  "message": "OK",
  "data": {
    "request_id": 42,
    "address": "0xabc...def",
    "network": "ETH",
    "currency": "USDT",
    "user_identifier": "user_8721",
    "status": "active",
    "display_expires_at": "2026-05-16T22:00:00+00:00",
    "created_at": "2026-05-16T19:00:00+00:00",
    "transactions": [
      {
        "tx_hash": "0x9a8...",
        "amount_decimal": "100.000000",
        "confirmations": 12,
        "status": "confirmed",
        "block_number": 21345678,
        "detected_at": "2026-05-16T19:30:00+00:00",
        "confirmed_at": "2026-05-16T19:35:30+00:00"
      }
    ]
  }
}

Top-level fields

Field	Type	Description
request_id	integer	Echoes the path parameter.
address	string	The on-chain address the user / payer should send funds to.
network	string	Network code (e.g. ETH).
currency	string	Currency symbol (e.g. USDT).
user_identifier	string | null	The sticky identifier you passed on allocation, or null for pool-allocated addresses.
status	string	Lifecycle state — see table below.
display_expires_at	ISO-8601 UTC	When you should stop showing this address to the end user. The gateway keeps monitoring the address after this, so late deposits still credit.
created_at	ISO-8601 UTC	When the request was allocated.
transactions	array	Every on-chain transaction observed against address for currency. May be empty.

status values

Value	Meaning
active	Address is being actively listened to; funds will be detected and credited.
expired_for_display	Past the display window; the gateway is still monitoring the address. Stop showing the address in your UI but keep polling for late confirmations.
settled	At least one deposit has confirmed and been credited to your balance.

transactions[] fields

Field	Type	Description
tx_hash	string	On-chain transaction hash.
amount_decimal	string	Amount in human units (decimal string, e.g. "100.000000").
confirmations	integer	Current confirmation count.
status	string	detected → confirmed → sweep_pending → swept, or failed at any step.
block_number	integer	The block in which this tx was first seen.
detected_at	ISO-8601 UTC	When the transaction was first detected on-chain.
confirmed_at	ISO-8601 UTC | null	When confirmations crossed network.min_confirmations. null while still pending.

Errors

Status	Cause
401 / 403 / 429	Standard middleware — see Errors page.
404	request_id doesn't exist, or belongs to another account.

Code samples

Examples assume sign_request(...) from the Authentication page.

curl + bash

REQUEST_ID="42"
METHOD="GET"
ENDPOINT="/v1/deposit-requests/${REQUEST_ID}"
QUERY=""
BODY=""

# ... sign as on the Authentication page ...

curl -sS "${BASE_URL}${ENDPOINT}" \
  -H "X-CPG-Key: ${API_KEY}" \
  -H "X-CPG-Timestamp: ${TS}" \
  -H "X-CPG-Signature: ${SIG}"

Python

request_id = 42
path = f"/v1/deposit-requests/{request_id}"
headers = sign_request("GET", path)
resp = requests.get(f"{BASE_URL}{path}", headers=headers, timeout=10)
resp.raise_for_status()
print(resp.json())

Node.js

const requestId = 42;
const path = `/v1/deposit-requests/${requestId}`;
const headers = signRequest('GET', path);
const resp = await fetch(`${BASE_URL}${path}`, { headers });
if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
console.log(await resp.json());

PHP

$requestId = 42;
$path = "/v1/deposit-requests/$requestId";
$headers = sign_request('GET', $path);
$ch = curl_init("$baseUrl$path");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
]);
echo curl_exec($ch);
curl_close($ch);

Notes

• Prefer webhooks over polling. Subscribe to deposit.detected / deposit.confirmed (covered in the Webhooks section) and only poll this endpoint as a fallback if a webhook delivery is missed.
• Sticky addresses surface their identifier here. If you allocated with user_identifier="user_8721", that string appears in user_identifier on every poll — convenient for your UI to associate the deposit with the right user without keeping an internal mapping.
• The transactions array can grow. If multiple deposits hit the same address (common for sticky addresses or pool-allocated addresses reused within their monitoring window), each one shows up as a separate entry.