Get settlement status

GET

/api/v4/partner/settlement/status/{quoteId}

Retrieve the current status and settlement details using the quote ID.

Authorizations

ApiKeyAuth

Type

API Key (header: X-Api-Key)

Parameters

Path Parameters

quoteId*

Type

string

Required

Responses

OK

Content-Type

application/json

{

"status": "ok",

"payload": {

"quoteId": "79a89717-3690-4db0-b434-39e25df01d55",

"timestamp": 1724247261,

"receivedDeadline": 1724247561,

"network": "ethereum",

"token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",

"receiveAddress": "0x1234....2345",

"totalAmountIn": "2811.242231",

"currency": "EUR",

"totalAmountSettled": "2623.34",

"status": "CONFIRMED"

}

}

GET

/api/v4/partner/settlement/status/{quoteId}

Playground

Authorization

ApiKeyAuth

Variables

Key

Value

quoteId*

Samples

Powered by VitePress OpenAPI

Code examples

curl

curl -X GET "https://api.brrr.network/api/v4/partner/settlement/status/q_abc123" \
  -H "X-Api-Key: YOUR_API_KEY"

JavaScript

const quoteId = 'q_abc123';

const response = await fetch(
  `https://api.brrr.network/api/v4/partner/settlement/status/${quoteId}`,
  {
    headers: {
      'X-Api-Key': process.env.BRRR_API_KEY,
    },
  }
);

if (!response.ok) {
  const error = await response.json();
  throw new Error(`Status check failed: ${error.errorCode}`);
}

const data = await response.json();
const status = data.payload?.status;
console.log('Settlement status:', status);

// Poll until terminal state
// Terminal states: 'FINISHED', 'ERROR', 'EXPIRED'

Python

import os
import httpx
import time

quote_id = 'q_abc123'

def poll_settlement_status(quote_id: str, max_attempts: int = 20) -> str:
    for attempt in range(max_attempts):
        response = httpx.get(
            f'https://api.brrr.network/api/v4/partner/settlement/status/{quote_id}',
            headers={'X-Api-Key': os.environ['BRRR_API_KEY']},
        )
        response.raise_for_status()
        status = response.json()['payload']['status']
        print(f'Attempt {attempt + 1}: status = {status}')

        if status in ('FINISHED', 'ERROR', 'EXPIRED'):
            return status

        time.sleep(15)  # wait 15 seconds between polls

    raise TimeoutError('Settlement did not reach a terminal state in time')

final_status = poll_settlement_status(quote_id)
print(f'Final settlement status: {final_status}')

Polling strategy

Poll this endpoint every 15–30 seconds after calling Execute Settlement. The settlement typically completes within a few minutes of the on-chain transfer being received by Holyheld. You will also receive a SETTLEMENT_STATUS_CHANGE webhook when the status changes.

Status reference

Status	Terminal?	Description
CREATED	No	Settlement received, not yet confirmed on-chain
CONFIRMED	No	On-chain transaction detected
PROCESSING	No	Holyheld is processing the fiat conversion
SENT	No	Fiat transfer initiated to the recipient
FINISHED	Yes	Settlement complete — fiat credited
ERROR	Yes	Settlement failed; contact support
EXPIRED	Yes	Quote expired before the transaction was detected