Transfer Beneficiary

post

https://api.blockpeer.finance/api/blockpeer-trade/transfer/beneficiary

Transfer the beneficiary designation to another party. Used when beneficiary rights need to be reassigned.

File Upload Format (Base64 Data URI)

For endpoints that accept file inputs, files must be submitted as a Base64-encoded Data URI string in the document field.

Format
data:<mimeType>;name=<filename>;base64,<base64EncodedContent>

Example
json
{ "document": "data:application/octet-stream;name=BL-0xd7.tt;base64,ewogICJAY29udGV4dCI6IFsKICAgICJodHRwcz..." }

Notes

Requires End User approval
Does not affect holder or owner roles

This API returns a URL with sessionId.
Use GET /auth/session-response?sessionId=<sessionId> to retrieve the session result.

Body Params

walletId

string

required

Identifier for the user's wallet, which will authorize the signing process for this transaction.

beneficiaryAddress

string

The blockchain address that will become the new beneficiary once the transaction is authorized. Only one of beneficiaryAddress or beneficiaryDomain should be provided.

beneficiaryDomain

string

The domain that will become the new beneficiary once the transaction is authorized. Only one of beneficiaryAddress or beneficiaryDomain should be provided.

remarks

string

Optional remarks or reference notes that will be formatted and recorded along with the transaction.

document

file

required

Signed document file from which the token identifier is extracted.

Headers

Idempotency-Key

string

Unique key to ensure idempotency for API requests.

X-External-Id

string

Unique external ID for tracking purposes, can be used for debugging and analytics.

Responses

Language

Credentials

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

File Upload Format (Base64 Data URI)

Notes

200The beneficiary transfer has been initialized successfully. A redirect URL is returned which leads to the signing interface. The user must authenticate there to complete the transfer.

400The request is missing required fields, contains invalid input, or the provided token is not included in the request header.

401The caller is not authorized to perform this transfer. This happens if the caller is not the current beneficiary or ownership validation fails.

409The transfer cannot proceed because the beneficiary address matches the caller’s own address, which is not permitted.

500Internal server error occurred while preparing or initializing the beneficiary transfer. This includes failures, blockchain estimation errors, or unexpected runtime exceptions.