Nominate Beneficiary

post

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

Nominate a beneficiary for the electronic trade document. Commonly used in financing or collateralisation workflows.

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

Beneficiary nomination does not transfer control
Approval required via redirect + passkeys

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 be used to sign the nomination transaction.

beneficiaryNomineeAddress

string

The blockchain address of the nominee who will be designated as the new beneficiary once nomination is confirmed. Only one of beneficiaryNomineeAddress or beneficiaryNomineeDomain should be provided.

beneficiaryNomineeDomain

string

The domain of the nominee who will be designated as the new beneficiary once nomination is confirmed. Only one of beneficiaryNomineeAddress or beneficiaryNomineeDomain should be provided.

remarks

string

Optional structured remarks that will be encoded and stored within the nomination transaction.

document

file

required

Signed document object used to extract the token Identifier.

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

File Upload Format (Base64 Data URI)

Notes

200The nomination process has been initialized successfully. The response contains a redirect URL to the signing interface, where the user must authenticate to complete the nomination transaction.

400The request is missing required fields, contains invalid data, or the authorization token is missing from the request header.

401The caller is unauthorized to nominate a beneficiary for this token. This occurs if the user is not recognized as a valid controller or validation checks fail.

409The nomination cannot proceed due to a logical conflict—for example, nominating the current beneficiary or providing an invalid nominee address.

500Unexpected internal server error occurred during the nomination process. This may include blockchain failures, communication issues, or transaction preparation errors.