Signing Messages & Typed Data

Beyond transactions, Customer Custody wallets allow users to sign off-chain data. This is essential for decentralized identity (DID), dApp authentication (Login with Wallet), or placing orders on decentralized exchanges.

1. Sign Plain Text or Hex Messages

Use this endpoint to sign a human-readable message or a hex-encoded string.

Endpoint: POST /v2/customers/{id}/sign/message

Request Body:

Code
{
  "walletId": "<customer_wallet_id>",
  "message": "Verify ownership of this account to login to Planbok App.",
  "memo": "Login Authentication",
  "redirectUrl": "https://yourapp.com/auth/callback"
}

• encodedByHex: Set to true if your message is a hex string (e.g., 0x...).
• memo: A human-readable note that will be displayed to the user on the Gateway.

2. Sign EIP-712 Typed Data (EVM)

For Ethereum and EVM-compatible chains, use this endpoint to sign structured data that is easier for users to read and verify.

Endpoint: POST /v2/customers/{id}/sign/typed-data

Request Body:

Code
{
  "walletId": "<customer_wallet_id>",
  "typedData": "{\"types\":{\"Message\":[{\"name\":\"content\",\"type\":\"string\"}]},\"primaryType\":\"Message\",\"domain\":{\"name\":\"App\",\"version\":\"1\",\"chainId\":1},\"message\":{\"content\":\"Hello world\"}}",
  "memo": "Approve Permission",
  "redirectUrl": "https://yourapp.com/sign-success"
}

The Signing Flow

1. Challenge Generation: The API returns a redirectUrl.
2. User Review: On the Gateway, the user sees the Message or Typed Data exactly as it was provided.
3. PIN Consent: The user entering their PIN acts as their cryptographic signature consent.
4. Result: After redirection, you can fetch the Signature (usually a hex string) from the challenge result or via webhook.

3. Retrieving & Verifying Signatures

Once the user has signed the message on the Gateway and is redirected back to your app, you must retrieve the signature.

Retrieving the Signature

Fetch the verified challenge to get the signature from the result field.

[!IMPORTANT] Account for Challenge Expiration: Challenges have a 15-minute lifespan. Ensure your application retrieves the signature and components (r, s, v) and stores them in your own backend immediately after the user is redirected back.

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

Challenge Result Example:

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

Verification

Once you have the signature, you can verify it on your backend using standard cryptographic libraries (e.g., ethers.js for EVM, @solana/web3.js for Solana).

Next Steps

Ensure your users can recover their account if they lose their device in Security & Recovery Management.