Signing APIs

Planbok provides a unified signing interface that abstracts the underlying cryptographic primitives (SECP256K1 and ED25519) across all supported blockchains. Signing operations are categorized based on the custody model of the target wallet.

Organizational Signing

These APIs are used for Organizational Wallets, where the organization manages the treasury and operational funds.

Transaction Builders

Before signing, you must build the transaction data using our high-level builders:

• Transfer: POST /v2/organization/transactions/transfer
• Contract Execution: POST /v2/organization/transactions/contract-execution

Raw Signing

For advanced use cases, you can sign raw data directly:

• Sign Message: POST /v2/organization/sign/message
• Sign Transaction: POST /v2/organization/sign/transaction
• Sign Typed Data: POST /v2/organization/sign/typed-data
• Sign Delegate Action: POST /v2/organization/sign/delegate-action (Restricted to NEAR Protocol chains)

[!IMPORTANT] All organizational signing requests must include the Encrypted Organization Secret (only required for Trustless MPC mode) and a unique idempotencyKey for security and consistency.

Customer Signing

These APIs are used for Customer Custody Wallets, where the end-user maintains sovereignty over their assets.

The Challenge/Response Flow

Customer signing follows a multi-step protocol to ensure the user's PIN never leaves their device:

1. Initiate: Call the transaction or sign endpoint to receive a challengeId.
2. Authenticate: The user enters their PIN on their device to "unwrap" their local MPC share.
3. Complete: The device responds to the challenge to finalize the signing protocol.

Endpoints:

• Transfer Challenge: POST /v2/customers/:id/transactions/transfer
• Sign Message Challenge: POST /v2/customers/:id/sign/message
• Sign Transaction Challenge: POST /v2/customers/:id/sign/transaction
• Sign Delegate Action Challenge: POST /v2/customers/:id/sign/delegate-action (Restricted to NEAR Protocol chains)

Unified Cryptographic Interface

Regardless of the route, Planbok's MPC protocol ensures that:

• No private key exists: The 2-of-2 shares are used to generate a valid signature without ever reconstructing the full private key.
• Cross-Chain Compatibility: The same API structure works for both EVM (secp256k1) and non-EVM (ed25519) chains.

For more on the underlying protocol, see MPC Infrastructure.