Developer Docs

Appearance

Execute settlement​

POST
/api/v4/partner/settlement/execute

Confirm a previously generated settlement quote and initiate settlement execution.

Authorizations​

ApiKeyAuth
Type
API Key (header: X-Api-Key)

Request Body​

application/json
JSON
{
"quoteId": "79a89717-3690-4db0-b434-39e25df01d55",
"timestamp": 1724247261,
"confirmDeadline": 1724247261,
"currency": "EUR",
"network": "ethereum",
"token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"totalAmountIn": "2811.242231",
"totalAmountSettled": "2623.34",
"totalAmountGBPReference": "2270.40",
"beneficiaries": [
{
"externalTransactionId": "string",
"customerId": "customer_a1b2c3d4",
"customerAddress": "0x1234....abcd",
"amountIn": "171.684232",
"amountSettled": "165.23",
"amountGBPReference": "142.99"
}
],
"ibanId": "iban_01HXYZ123456",
"reference": "Invoice #2024-0042"
}

Responses​

OK

application/json
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"
}
}

Playground​

Authorization
Body

Samples​

Powered by VitePress OpenAPI

Code examples ​

The request body is the payload object returned by Create a Settlement Quote. Pass it through directly — do not modify any fields.

bash
# Use the exact payload returned by POST /api/v4/partner/settlement/quote
curl -X POST https://api.brrr.network/api/v4/partner/settlement/execute \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "q_abc123",
    "timestamp": 1711753200,
    "confirmDeadline": 1711754100,
    "currency": "EUR",
    "network": "ethereum",
    "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "totalAmountIn": "102.50",
    "totalAmountSettled": "100.00",
    "totalAmountGBPReference": "86.42",
    "beneficiaries": [
      {
        "externalTransactionId": "txn_001",
        "customerId": "cust_a1b2c3d4",
        "customerAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "amountIn": "102.50",
        "amountSettled": "100.00",
        "amountGBPReference": "86.42"
      }
    ]
  }'
javascript
// Step 1: Create a quote
const quoteResponse = await fetch('https://api.brrr.network/api/v4/partner/settlement/quote', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.BRRR_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    currency: 'EUR',
    network: 'ethereum',
    token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
    beneficiaries: [
      {
        externalTransactionId: 'txn_001',
        customerId: 'cust_a1b2c3d4',
        customerAddress: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
        quoteType: 'fiat_to_token',
        amount: '100.00',
      },
    ],
  }),
});

const quoteData = await quoteResponse.json();
const quotePayload = quoteData.payload; // Pass this directly to execute

// Step 2: Execute the quote — send the full payload object as the body
const executeResponse = await fetch('https://api.brrr.network/api/v4/partner/settlement/execute', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.BRRR_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(quotePayload), // pass through unchanged
});

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

const result = await executeResponse.json();
const settlement = result.payload;

console.log('Settlement accepted. Quote ID:', settlement.quoteId);
console.log('Send', settlement.totalAmountIn, settlement.token, 'to:', settlement.receiveAddress);
console.log('Transfer deadline:', new Date(settlement.receivedDeadline * 1000).toISOString());
python
import os
import httpx
from datetime import datetime

headers = {
    'X-Api-Key': os.environ['BRRR_API_KEY'],
    'Content-Type': 'application/json',
}

# Step 1: Create a quote
quote_response = httpx.post(
    'https://api.brrr.network/api/v4/partner/settlement/quote',
    headers=headers,
    json={
        'currency': 'EUR',
        'network': 'ethereum',
        'token': '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
        'beneficiaries': [
            {
                'externalTransactionId': 'txn_001',
                'customerId': 'cust_a1b2c3d4',
                'customerAddress': '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
                'quoteType': 'fiat_to_token',
                'amount': '100.00',
            }
        ],
    },
)
quote_response.raise_for_status()
quote_payload = quote_response.json()['payload']  # Pass this directly to execute

# Step 2: Execute the quote — send the full payload object as the body
execute_response = httpx.post(
    'https://api.brrr.network/api/v4/partner/settlement/execute',
    headers=headers,
    json=quote_payload,  # pass through unchanged
)
execute_response.raise_for_status()
settlement = execute_response.json()['payload']

print(f"Settlement accepted. Quote ID: {settlement['quoteId']}")
print(f"Send {settlement['totalAmountIn']} {settlement['token']} to: {settlement['receiveAddress']}")
deadline = datetime.fromtimestamp(settlement['receivedDeadline']).isoformat()
print(f"Transfer deadline: {deadline}")

Transfer required after execution

After a successful execute response, you must send the token transfer to the receiveAddress returned in the response before the receivedDeadline. Holyheld will not credit the settlement until the on-chain transfer is received. Always use the receiveAddress from this response — never cache a previous value.