Signing Messages & Typed Data

Organizational Custody supports off-chain signing, allowing your system to authenticate users, sign for dApps, or place orders on decentralized exchanges without broadcasting a transaction to the blockchain.

1. Sign Plain Text or Hex Messages

Use this endpoint to sign a message string using your wallet's private key shards.

Endpoint: POST /v2/organization/sign/message
Headers:

• PLANBOK-X-API-KEY: <your_api_key>

Request Body:

Code
{
  "walletId": "<wallet_id>",
  "message": "Authenticate for Planbok API Explorer",
  "memo": "Login Signature",
  "encodedByHex": false
}

• encodedByHex: If true, the message string must be a valid hex string (e.g., 0x...).

2. Sign EIP-712 Typed Data (EVM)

For Ethereum and EVM-compatible chains, use this endpoint to sign structured data that follows the EIP-712 standard.

Endpoint: POST /v2/organization/sign/typed-data

Request Body:

Code
{
  "walletId": "<wallet_id>",
  "typedData": "{\"types\":{\"Message\":[{\"name\":\"content\",\"type\":\"string\"}]},\"primaryType\":\"Message\",\"domain\":{\"name\":\"App\",\"version\":\"1\",\"chainId\":1},\"message\":{\"content\":\"Hello world\"}}",
  "memo": "Structured Signature"
}

3. Trustless MPC Requirements

Just like transaction signing, message signing in Trustless MPC mode requires the encryptedOrganizationSecret.

Code
{
  ...
  "encryptedOrganizationSecret": "BASE64_CIPHERTEXT"
}

4. Retrieving the Signature

The API returns a challengeId. For Organizational Custody, this challenge is typically processed immediately by the system (standard MPC) or upon receipt of your secret (trustless MPC).

The response data will contain the final signature details:

Code
{
  "success": true,
  "data": {
    "status": "success",
    "result": {
      "signature": "0x7d92...",
      "r": "...",
      "s": "...",
      "v": 27
    }
  }
}

Next Steps

In case of network congestion, learn how to manage your transactions in the Managing Transactions guide.