Sign a proposal

LifecycleUser Wallet KYC Rail Fund Move money

This page shows you how to turn a proposal’s signing payload into a signature BMONI accepts, and how to work out why a signature was rejected. Signing is the step where most integrations stall, and almost always for one of three reasons: you signed through the wrong library method, your v byte is 0/1 instead of 27/28, or your payload expired. Each has a specific symptom, listed under Why your signature is rejected.

This step moves money. Once the required signatures are collected, the proposal executes on-chain and cannot be recalled. Test against the sandbox first.

Before you start

You need:

A proposal in status PENDING_SIGNATURES, or PENDING_APPROVALS if you are capturing a co-signer early.
The private key for the address you registered as userOwnerAddress when you created the smart wallet.
One of ethers 6, viem 2, or eth-account 0.13 (used by web3.py).

What you are actually signing

GET /v1/users/{userId}/smart-wallets/proposals/{proposalId}/sign-payload hands you a digest that has already been constructed for you. You do not build the EIP-712 domain or types yourself. The backend prepares the structured data, hashes it, and gives you the resulting 32-byte digest in hashToSign. That single fact removes most of the difficulty. Your job is to produce a raw secp256k1 signature over those 32 bytes — nothing more.

GET /v1/users/{userId}/smart-wallets/proposals/{proposalId}/sign-payload

{
  "success": true,
  "data": {
    "method": "evm",
    "walletIndex": 0,
    "workflowId": "proposal-sign-47665949",
    "hashToSign": "0x8f5156823a5c2cdc7bedc12253e49e4946c6fff0273034eb485750035d21ad31",
    "payload": "0x8f5156823a5c2cdc7bedc12253e49e4946c6fff0273034eb485750035d21ad31",
    "deadline": "2026-08-07T13:05:00.000Z",
    "proposalId": "47665949-8654-4461-b52a-3ef3624b1234",
    "userOpHash": "0x8f5156823a5c2cdc7bedc12253e49e4946c6fff0273034eb485750035d21ad31",
    "safeTxHash": null,
    "typedData": null
  }
}

Field	What it is
`method`	`evm` or `solana`. Everything on this page describes `evm`.
`walletIndex`	Index of the key the signature must come from. `0` for a single-owner smart wallet.
`workflowId`	Internal workflow identifier. Echo it back only where an endpoint asks for it.
`hashToSign`	The 32-byte digest you sign. Always present for `evm`.
`payload`	Equal to `hashToSign` for `evm`. Present for parity with non-EVM chains.
`deadline`	ISO 8601 instant after which the signature is refused.
`userOpHash`	Set when the proposal executes as an ERC-4337 user operation (a relay-only proposal).
`safeTxHash`	Set when the proposal executes as a Safe transaction (a multi-signature proposal).
`typedData`	The full EIP-712 object, when the upstream includes it. Informational — see below.

Sign `hashToSign`, not `typedData`

Exactly one of userOpHash or safeTxHash is set, and it tells you which hash hashToSign is:

Relay-only proposal — userOpHash is set. hashToSign is the EIP-712 digest of the ERC-4337 user operation.
Multi-signature proposal — safeTxHash is set. hashToSign is the Safe transaction hash.

Either way you sign hashToSign. The distinction matters for understanding what you are authorising, not for the signing call.

typedData is populated only when the upstream includes the full EIP-712 object, and it is null otherwise. Treat it as a debugging aid for inspecting what the digest covers. Do not re-hash it and do not pass it to a signTypedData method — you will produce a different digest from the one the backend is expecting, and the signature will be rejected.

Sign the digest

The rule in every language is the same: use the method that signs a raw hash, not the one that signs a message. A message-signing method applies the EIP-191 prefix \x19Ethereum Signed Message:\n32 and hashes your digest a second time.

This rule applies to proposal signing only. The other place you sign with the owner key — the owner-proof challenge at wallet creation — wants the opposite: a text message signed with the EIP-191 prefix, so signMessage is correct there. Confusing the two is the most common signing mistake. See the side-by-side comparison.

All three snippets below produce a byte-identical signature. Each is verified against the test vector in Reproduce a known-good signature.

import { ethers } from 'ethers'

const wallet = new ethers.Wallet(OWNER_PRIVATE_KEY)

// signingKey.sign() signs the raw digest.
// Do NOT use wallet.signMessage() — it applies the EIP-191 prefix.
const signature = wallet.signingKey.sign(signPayload.hashToSign).serialized

await fetch(
  `${BASE_URL}/v1/users/${bmoniUserId}/smart-wallets/proposals/${proposalId}/sign`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': API_KEY,
    },
    body: JSON.stringify({ signature }),
  },
)

import { sign } from 'viem/accounts'

// sign() from viem/accounts signs the raw digest and serialises v as 27/28.
// Do NOT use account.signMessage() — it applies the EIP-191 prefix.
const signature = await sign({
  hash: signPayload.hashToSign,
  privateKey: OWNER_PRIVATE_KEY,
  to: 'hex',
})

await fetch(
  `${BASE_URL}/v1/users/${bmoniUserId}/smart-wallets/proposals/${proposalId}/sign`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': API_KEY,
    },
    body: JSON.stringify({ signature }),
  },
)

import requests
from eth_account import Account

# unsafe_sign_hash() signs the raw digest. The name warns you to be sure the
# hash is one you trust — here it comes from the sign-payload endpoint.
# Do NOT use Account.sign_message() — it applies the EIP-191 prefix.
signed = Account.unsafe_sign_hash(
    bytes.fromhex(sign_payload["hashToSign"][2:]),
    OWNER_PRIVATE_KEY,
)

requests.post(
    f"{BASE_URL}/v1/users/{bmoni_user_id}"
    f"/smart-wallets/proposals/{proposal_id}/sign",
    json={"signature": "0x" + signed.signature.hex()},
    headers={"x-api-key": API_KEY},
    timeout=30,
)

On eth-account older than 0.13, unsafe_sign_hash is named signHash. Upgrade rather than pin: the older name is deprecated and removed in 0.13.

Submit the signature

POST /v1/users/{userId}/smart-wallets/proposals/{proposalId}/sign
{
  "signature": "0x628f1aff48c9d1f35d45a735eb026db0437c5ed334a94dc7fb0ac86ca32c10bd173a653a7f064c4512244f6fcbefb07e13bfe7368fcacdcc4e6fb153f50050991b"
}

The backend recovers the signer address from the signature, checks it against the proposal’s signer snapshot, and records it. When the collected signatures reach requiredSignatures, the proposal is submitted on-chain.

Expected result

A 200 response carrying the updated proposal. Its status stays PENDING_SIGNATURES while further signatures are outstanding, and becomes COMPLETED after on-chain execution settles. Poll GET /v1/users/{userId}/smart-wallets/proposals/{proposalId} for the terminal status.

Reproduce a known-good signature

Run this before you debug your integration. It uses the well-known Anvil test account, so you can confirm your toolchain produces the exact bytes BMONI expects without touching a real key or a real proposal. The digest is keccak256 of a fixed string, so you can regenerate every value here from scratch:

Value
Preimage	`bmoni-embedded:BKE-2041:sign-payload-example`
Private key	`0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80`
Owner address	`0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266`
`hashToSign`	`0x8f5156823a5c2cdc7bedc12253e49e4946c6fff0273034eb485750035d21ad31`
Signature	`0x628f1aff48c9d1f35d45a735eb026db0437c5ed334a94dc7fb0ac86ca32c10bd173a653a7f064c4512244f6fcbefb07e13bfe7368fcacdcc4e6fb153f50050991b`
`v` byte	`27` (`0x1b`)

That private key is the public Anvil and Hardhat test account. It is published in their documentation, holds nothing, and must never be used for anything but local testing.

import assert from 'node:assert/strict'
import { ethers } from 'ethers'
import { sign } from 'viem/accounts'
import { keccak256, toHex } from 'viem'

const PK = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80'
const hash = keccak256(toHex('bmoni-embedded:BKE-2041:sign-payload-example'))
const expected =
  '0x628f1aff48c9d1f35d45a735eb026db0437c5ed334a94dc7fb0ac86ca32c10bd' +
  '173a653a7f064c4512244f6fcbefb07e13bfe7368fcacdcc4e6fb153f50050991b'

assert.equal(hash, '0x8f5156823a5c2cdc7bedc12253e49e4946c6fff0273034eb485750035d21ad31')
assert.equal(new ethers.Wallet(PK).signingKey.sign(hash).serialized, expected)
assert.equal(await sign({ hash, privateKey: PK, to: 'hex' }), expected)
assert.equal(
  ethers.recoverAddress(hash, expected),
  '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
)

console.log('Toolchain produces the expected signature.')

from eth_account import Account
from eth_utils import keccak

PK = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
digest = keccak(text="bmoni-embedded:BKE-2041:sign-payload-example")
expected = (
    "0x628f1aff48c9d1f35d45a735eb026db0437c5ed334a94dc7fb0ac86ca32c10bd"
    "173a653a7f064c4512244f6fcbefb07e13bfe7368fcacdcc4e6fb153f50050991b"
)

assert "0x" + digest.hex() == (
    "0x8f5156823a5c2cdc7bedc12253e49e4946c6fff0273034eb485750035d21ad31"
)
signed = Account.unsafe_sign_hash(digest, PK)
assert "0x" + signed.signature.hex() == expected
assert signed.v == 27
assert Account._recover_hash(digest, signature=signed.signature) == (
    "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
)

print("Toolchain produces the expected signature.")

If your output differs from expected, the fault is in your signing code, not in your proposal. Work through the next section.

Why your signature is rejected

`Point is not on curve`

The bytes you sent are not a decodable secp256k1 signature. Check, in order:

Length. A signature is exactly 65 bytes — 0x plus 130 hex characters. A 64-byte signature is missing its v byte; a 66-byte one usually has a stray 0x in the middle from concatenating r, s, and v as prefixed strings.
Encoding. Send hex, not base64, and not a byte array serialised as JSON.
Component order. The layout is r (32 bytes), then s (32 bytes), then v (1 byte). Assembling v first, or s before r, produces bytes that decode to a point off the curve.

// Assert before you send. This catches every length and encoding fault.
if (!/^0x[0-9a-fA-F]{130}$/.test(signature)) {
  throw new Error(`Malformed signature: expected 65 bytes, got ${signature}`)
}

`Invalid yParityOrV`

Your v byte is 0 or 1. Some libraries return the raw recovery bit as yParity; BMONI expects the Ethereum convention of 27 or 28. Normalise the last byte:

const v = parseInt(signature.slice(-2), 16)
const normalised =
  v < 27 ? signature.slice(0, -2) + (v + 27).toString(16).padStart(2, '0') : signature

The snippets in Sign the digest already emit 27/28. You hit this when assembling r, s, and v by hand from a lower-level library.

`500`, or the signature is recorded but never executes

You almost certainly signed through a message-signing method. This is the most common failure and the hardest to spot, because the signature is structurally valid — it decodes cleanly and has a correct v byte. It simply recovers to a different address, so it never matches the proposal’s signer snapshot. Using the test vector above, the two paths diverge like this:

Method	Recovers to
`signingKey.sign(hash)`	`0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266`	Correct — the registered owner.
`wallet.signMessage(hash)`	`0xC69f336bb0C1e391a97861cC1837e1f10a9Ba041`	Wrong — rejected.

Replace the call as follows:

Library	Do not use	Use
ethers	`wallet.signMessage(hash)`	`wallet.signingKey.sign(hash).serialized`
viem	`account.signMessage({ message: { raw: hash } })`	`sign({ hash, privateKey, to: 'hex' })`
eth-account	`Account.sign_message(encode_defunct(...))`	`Account.unsafe_sign_hash(digest, key)`

`Signature deadline exceeded`

The deadline in the sign payload has passed. Fetch a fresh payload with GET …/sign-payload and sign again. Do not cache a payload across a user session — fetch it immediately before signing.

The recovered signer is not authorised

The signature is valid but the address is not on the proposal’s signer snapshot. The signing key must be the one registered as userOwnerAddress at wallet creation. If you rotate keys in your own store between wallet creation and signing, the snapshot still holds the original address.

Validating a signature without moving money

There is currently no endpoint that validates a signature without submitting it. Until one exists, use the test vector on this page to prove your toolchain end to end, then run a minimum-value proposal in the sandbox as your first live exercise.

A sandbox validate-only endpoint is tracked as platform work. When it ships, this section will describe it.

Transfers — creating and approving the proposal you sign here.
Errors and status codes — every error this endpoint can return.
SDK signing — signing through bmoni_embedded_sdk instead of a raw key.
Sandbox test data — values that resolve in the sandbox.

Last reviewed: 7 August 2026. Snippets verified against ethers 6.17.0, viem 2.55.10, and eth-account 0.13.7.

API

KYC

Rails

Money movement

Cards

Before you start

What you are actually signing

Sign `hashToSign`, not `typedData`

Sign the digest

Submit the signature

Expected result

Reproduce a known-good signature

Why your signature is rejected

`Point is not on curve`

`Invalid yParityOrV`

`500`, or the signature is recorded but never executes

`Signature deadline exceeded`

The recovered signer is not authorised

Validating a signature without moving money

​Before you start

​What you are actually signing

​Sign hashToSign, not typedData

​Sign the digest

​Submit the signature

​Expected result

​Reproduce a known-good signature

​Why your signature is rejected

​Point is not on curve

​Invalid yParityOrV

​500, or the signature is recorded but never executes

​Signature deadline exceeded

​The recovered signer is not authorised

​Validating a signature without moving money

​Related

Before you start

What you are actually signing

Sign `hashToSign`, not `typedData`

Sign the digest

Submit the signature

Expected result

Reproduce a known-good signature

Why your signature is rejected

`Point is not on curve`

`Invalid yParityOrV`

`500`, or the signature is recorded but never executes

`Signature deadline exceeded`

The recovered signer is not authorised

Validating a signature without moving money

Related