BSV blockchainBSV blockchain

Get message delivery quote(s)

GET/permissions/quote

Returns pricing information for sending a message to one or more recipients in a named message box. The caller (sender) is identified by their auth headers.

Single-recipient response uses the legacy shape { status, description, quote: { deliveryFee, recipientFee } }.

Multi-recipient response adds quotesByRecipient, totals, and blockedRecipients fields. Blocked recipients are still returned in the list; the caller decides whether to abort or proceed with the non-blocked subset.

Persisted recipient fees are safe integers from -1 through 2147483647; server delivery fees are safe integers from 0 through 2147483647. Invalid persisted values fail the quote closed.

Query Parameters

recipientstringrequired

Identity key of the recipient. Repeat the parameter for multiple recipients: ?recipient=A&recipient=B.

messageBoxstringrequired

Message box type to quote against.

Response

Quote(s) generated.

status"success"
descriptionstring
quoteobject
Show quote properties
deliveryFeeinteger

Server delivery fee in satoshis.

recipientFeeinteger

Recipient-set fee in satoshis (-1 = blocked).

Missing or invalid parameters. Codes: ERR_MISSING_PARAMETERS, ERR_INVALID_PUBLIC_KEY

status"error"
codestring

Machine-readable error code (see specs/errors.md).

descriptionstring

Human-readable explanation.

Authentication required (ERR_AUTHENTICATION_REQUIRED).

status"error"
codestring

Machine-readable error code (see specs/errors.md).

descriptionstring

Human-readable explanation.

Internal server error (ERR_INTERNAL).

status"error"
codestring

Machine-readable error code (see specs/errors.md).

descriptionstring

Human-readable explanation.

Request
curl -X GET "https://{host}/permissions/quote?recipient=<recipient>&messageBox=<messageBox>" \
  -H "x-bsv-auth-identity-key: <x-bsv-auth-identity-key>"
Response
{
  "status": "success",
  "description": "string",
  "quote": {
    "deliveryFee": 0,
    "recipientFee": 0
  }
}