Customer-Authorized Transactions

In the Customer Custody model, all outgoing transactions must be explicitly authorized by the user using their PIN. Planbok converts transaction requests into Challenges that the user resolves on the secure Planbok Gateway.

The Transaction Lifecycle

1. Initiate: You request a transfer or contract call via the API.
2. Challenge: Planbok returns a challengeId and a redirectUrl.
3. Authorize: The user verifies the transaction details and enters their PIN on the Gateway.
4. Broadcast: Once PIN-verified, the Planbok MPC nodes combine shares to sign and broadcast the transaction to the blockchain.
5. Confirm: The user is redirected back to your app, and you can track the transactionId.

1. Token Transfers

Use this endpoint to send native or ERC-20/SPL tokens.

Endpoint: POST /v2/customers/{id}/transactions/transfer

Request Body:

Code
{
  "idempotencyKey": "<unique_uuid_v4>",
  "walletId": "<customer_wallet_id>",
  "destinationAddress": "0xabc...",
  "tokenId": "<token_id>",
  "amounts": ["0.5"],
  "redirectUrl": "https://yourapp.com/transfer-success"
}

2. Contract Executions

Use this endpoint for complex interactions like Swaps, NFT Mints, or Staking.

Endpoint: POST /v2/customers/{id}/transactions/contract-execution

Request Body:

Code
{
  "idempotencyKey": "<unique_uuid_v4>",
  "walletId": "<customer_wallet_id>",
  "contractAddress": "0xcontract...",
  "abiFunctionSignature": "mint(address,uint256)",
  "abiParameters": ["0xuser...", "1"],
  "redirectUrl": "https://yourapp.com/mint-success"
}

3. Handling the Gateway Redirect

The response for both endpoints will contain a redirectUrl. When the user lands on the Gateway:

• Verification: The Gateway displays the transaction details (Recipient, Amount, Contract Method) for the user to review.
• PIN Entry: The user enters their PIN to unlock their MPC shard.
• Signing: The Gateway and Planbok nodes perform the multi-party computation to generate the signature.

4. Tracking Completion

After the user is redirected back to your site, you can retrieve the transaction result.

Option A: From the Challenge Result (Recommended)

You can fetch the hash and internal transaction ID directly from the verified challenge.

[!IMPORTANT] Challenges are short-lived (15 minutes). Your system must retrieve the transactionId and transactionHash from the challenge result and store them immediately. Once a challenge is pruned, this result data is no longer accessible via the challenge ID.

Endpoint: GET /v2/customers/{id}/challenges/{challengeId}

Response Example:

Code
{
  "data": {
    "status": "verified",
    "result": {
      "success": true,
      "transactionId": "69a53d... (Planbok ID)",
      "transactionHash": "0xabc123... (Blockchain Hash)"
    }
  }
}

Option B: Listing All Customer Transactions

You can also list all transactions for the customer to find the latest ones.

Endpoint: GET /v2/customers/{id}/transactions

Option C: Webhooks (Asynchronous)

For production systems, we recommend listening for webhooks. Planbok will push the result to your configured endpoint as soon as it's processed.

Relevant Events:

• transaction.broadcast: Triggered as soon as the MPC signing is complete and the transaction is sent to the network. Contains the transactionHash.
• transaction.confirmed: Triggered once the transaction is included in a block.
• transaction.failed: Triggered if the PIN was correct but the transaction could not be broadcast (e.g., insufficient gas).

[!TIP] Always use Webhooks for the most reliable, real-time updates in your UI.

Next Steps

For non-transactional signing (like login), see Signing Messages & Typed Data.