BSV blockchainBSV blockchain

Set a message permission for a sender or as a box-wide default

POST/permissions/set

Sets the recipientFee for messages arriving in a named message box.

  • If sender is omitted the setting is a box-wide default for all senders.
  • If sender is provided, the setting applies only to that sender.
  • recipientFee semantics:
    • -1 — block all messages from this sender (or box-wide)
    • 0 — always allow (no fee required)
    • >0 — require this many satoshis before delivery

Body application/json

senderstring

Compressed secp256k1 public key encoded as a 66-character hex string.

messageBoxstringrequired

Message box name (e.g. notifications, inbox).

recipientFeeintegerrequired

-1 = blocked, 0 = always allow, positive = satoshi amount.

Response

Permission set or updated successfully.

status"success"
descriptionstring

Human-readable confirmation of the new policy.

Invalid request. Codes: ERR_INVALID_REQUEST, ERR_INVALID_PUBLIC_KEY, ERR_INVALID_FEE_VALUE, ERR_INVALID_MESSAGE_BOX

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_DATABASE_ERROR, ERR_INTERNAL).

status"error"
codestring

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

descriptionstring

Human-readable explanation.

Request
curl -X POST "https://{host}/permissions/set" \
  -H "Content-Type: application/json" \
  -H "x-bsv-auth-identity-key: <x-bsv-auth-identity-key>" \
  -d '{
  "sender": "string",
  "messageBox": "string",
  "recipientFee": 0
}'
Response
{
  "status": "success",
  "description": "string"
}