Settlement estimation

Before executing a settlement, you must request a quote. The quote locks in conversion rates for a set of beneficiaries and returns a quoteId required for Settlement execution.

Where estimation fits in the flow

  Risk assessment: LOW or MEDIUM
           │
           ▼
  POST /partner/settlement/quote          ← you are here
  • specify currency, network, token
  • list one or more beneficiaries
  • choose quoteType per beneficiary
           │
           ▼
  Quote returned:
  { quoteId, totalAmountIn, confirmDeadline, beneficiaries[] }
           │
           │  valid for 15 minutes
           ▼
  POST /partner/settlement/execute
  → send tokens on-chain to receiveAddress

Quote types

Each beneficiary in the request specifies a quoteType:

quoteType	When to use	amount field means
fiat_to_token	You know the fiat amount to settle	Amount in the requested fiat currency (2 decimal places)
token_to_fiat	You know the token amount to send	Token amount in the token's native precision

All beneficiaries in a single quote must share the same currency, network, and token. Mixed currencies or networks require separate quotes.

What a quote contains

A successful response includes:

Field	Description
quoteId	Unique identifier
confirmDeadline	Unix timestamp after which the quote expires (typically 15 minutes from creation)
totalAmountIn	Exact token amount to transfer on-chain when executing
totalAmountSettled	Total fiat amount that will be distributed to all beneficiaries
beneficiaries[]	Per-beneficiary breakdown with individual amountIn and amountSettled

Where does receiveAddress come from?

receiveAddress — the BRRR wallet address you send tokens to — is returned by Execute Settlement, not by the quote endpoint. Always use the address from the execute response; never cache or reuse an address from a previous settlement.

Fulfillment validation

Each beneficiary is validated when the quote is created. A beneficiary is denied (and excluded from the quote) if:

Reason	reason value
Customer or address not found	NOT_FOUND
Risk assessment not yet available	RISK_UNAVAILABLE
Risk level is HIGH or VERY HIGH	RISK_LEVEL

If any beneficiary is denied, the entire request returns a 400 FULFILLMENT_DENIED error with a payload array listing each denied beneficiary and their reason. No partial quote is returned — fix the denied beneficiaries and re-submit.

Handling partial failures

If only some beneficiaries are denied, remove them from the request and re-submit with the remaining eligible beneficiaries. Contact support@holyheld.com for guidance on denied beneficiaries.

Quote expiry

Quotes are valid for 15 minutes from creation (confirmDeadline). If you do not call Execute Settlement before the deadline:

1. The quote expires — the quoteId cannot be used
2. Create a new quote before executing

Do not cache quotes

Exchange rates change. Always use the quoteId from the most recent quote request. Never reuse a quoteId from a previous session or a cached response.

Re-estimation

If market conditions change between quote creation and execution, or if you need to adjust the beneficiary list, simply create a new quote. Each call to POST /partner/settlement/quote generates a fresh quoteId with updated rates and a new 15-minute window.

Next steps

Pass the full quote payload from the quote response to Settlement execution. The execute response provides the receiveAddress to send tokens to on-chain.