Quickstart — zero to first send

LifecycleUser Wallet KYC Rail Fund Move money

This page walks a brand-new sandbox user all the way to a settled transfer, using real values so every call runs as written. Eleven calls, in one order. The order matters more than it looks: wallet creation comes before onboarding, because onboarding needs the wallet address.

This is the server-side API walkthrough. If you are building a Flutter app with bmoni_embedded_sdk, start with the SDK quickstart instead — it covers the client side of the same lifecycle.

Before you start

A sandbox API key, sent as x-api-key on every request.
A provisioned wallet from bmoni_embedded_sdk. Its address becomes userOwnerAddress, and the SDK signs twice below.
The Bunch Dillon persona from Sandbox test data. Use its details verbatim — verification matches them.

export BASE_URL="https://embedded-dev.bmoni.com"
export API_KEY="pk_a025cacbf33a_76fb864113f3540909de5b1da39cc146906e35b1c6d4d1e4"

That shared sandbox key works against the development base URL only. Get your own key before you touch production, whose base URL is https://embedded.bmoni.com — see Base URL.

You sign twice in this flow, with two different methods. Step 3 signs a text message with the EIP-191 prefix. Step 11 signs a raw 32-byte digest without it. Using the wrong one for either step fails, and the errors do not say which mistake you made. Each step below names the method explicitly.

1. Create the user

Use the persona’s name and phone, converted to E.164.

POST /v1/users
{
  "firstName": "Bunch",
  "lastName": "Dillon",
  "email": "bunch.dillon@example.com",
  "phoneNumber": "+2348000000000"
}

Keep bmoniUserId from the response. It is the {userId} path parameter for every later call — not your own employee identifier.

A 409 here means a user already holds that email or phone. The message names which. That is the correct response to a retry of a create that already succeeded — recover the existing user rather than retrying. See Retries and duplicates.

2. Submit the KYC profile

PATCH /v1/users/{userId}/kyc
{
  "personalInfo": {
    "firstName": "Bunch",
    "lastName": "Dillon",
    "dateOfBirth": "1990-01-15",
    "gender": "male"
  },
  "addressDetails": {
    "street": "15 Admiralty Way",
    "city": "Lagos",
    "state": "Lagos",
    "countryCode": "NGA"
  }
}

Do not send occupation as free text. An occupation that does not resolve to a code is silently dropped — the call returns success and your employment data is gone. Fetch a code from GET /v1/users/{userId}/kyc/occupations?search=… and send occupationCode instead. See Employment data is dropped.

3. Prove you control the owner address

Wallet creation requires the owner address to prove control first.

POST /v1/users/{userId}/smart-wallets/owner-proof-challenges
{
  "currency": "CNGN",
  "userOwnerAddress": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
}

The response carries a challengeId and a message. Sign the message as text, with the EIP-191 prefix — the standard personal_sign your language’s Ethereum library already provides.

import { ethers } from 'ethers'

const wallet = new ethers.Wallet(OWNER_PRIVATE_KEY)

// signMessage applies the EIP-191 prefix, which is what this step wants.
const ownerProofSignature = await wallet.signMessage(challenge.message)

from eth_account import Account
from eth_account.messages import encode_defunct

signed = Account.sign_message(
    encode_defunct(text=challenge["message"]),
    OWNER_PRIVATE_KEY,
)
owner_proof_signature = "0x" + signed.signature.hex()

import (
    "encoding/hex"

    "github.com/ethereum/go-ethereum/accounts"
    "github.com/ethereum/go-ethereum/crypto"
)

key, _ := crypto.HexToECDSA(ownerPrivateKey) // no 0x prefix

// TextHash applies the EIP-191 prefix.
sig, _ := crypto.Sign(accounts.TextHash([]byte(challenge.Message)), key)
sig[64] += 27 // go-ethereum returns v as 0/1; Ethereum expects 27/28

ownerProofSignature := "0x" + hex.EncodeToString(sig)

use Elliptic\EC;
use kornrunner\Keccak;

// EIP-191: prefix the message, then hash, then sign.
$prefixed = "\x19Ethereum Signed Message:\n" . strlen($challenge['message']) . $challenge['message'];
$digest   = Keccak::hash($prefixed, 256);

$sig = (new EC('secp256k1'))
    ->keyFromPrivate($ownerPrivateKey)
    ->sign($digest, ['canonical' => true]);

$ownerProofSignature = '0x'
    . str_pad(gmp_strval($sig->r->toString(), 16), 64, '0', STR_PAD_LEFT)
    . str_pad(gmp_strval($sig->s->toString(), 16), 64, '0', STR_PAD_LEFT)
    . dechex($sig->recoveryParam + 27);

Step 11 signs differently — see the comparison. The challenge expires after 10 minutes and is consumed on successful wallet creation. Request a fresh one if you are slow or if creation fails.

4. Create the smart wallet

POST /v1/users/{userId}/smart-wallets/create-managed
{
  "currency": "CNGN",
  "userOwnerAddress": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
  "ownerProofChallengeId": "…",
  "ownerProofSignature": "0x…"
}

One call handles prepare, sign, deploy, and owner registration. Keep the returned smartWalletId and the wallet address.

5. Start onboarding

Now that the wallet exists, onboarding can reference it. This is why wallet creation comes first — ngnWalletAddress is required here.

POST /v1/users/{userId}/onboarding/start-nigeria
{
  "bvn": "95888168924",
  "ngnWalletAddress": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
  "ngnWalletIndex": 0
}

That BVN is Bunch Dillon’s. It resolves because the profile in step 2 carries the matching name.

6, 7, 8. Upload the documents

Three separate uploads. All three are required before verification can complete.

POST /v1/users/{userId}/kyc/documents/identification
POST /v1/users/{userId}/kyc/documents/proof-of-address
POST /v1/users/{userId}/kyc/documents/biometric

Each takes a multipart file. JPEG or PNG.

curl -X POST "$BASE_URL/v1/users/$USER_ID/kyc/documents/identification" \
  -H "x-api-key: $API_KEY" \
  -F "file=@id-front.jpg"

Then poll until the rail is active:

GET /v1/users/{userId}/onboarding/status

Do not poll this in production. Subscribe to onboarding.completed, onboarding.failed, and kyc.action_required instead — see Webhooks and events.

9. Create the transfer proposal

Nothing moves yet. A proposal records intent.

POST /v1/users/{userId}/smart-wallets/{smartWalletId}/proposals
{
  "proposal": {
    "type": "TRANSFER",
    "toAddress": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
    "amount": "25.00",
    "currency": "CNGN",
    "description": "First send"
  }
}

Keep the proposal id.

Sending to toUserId instead of toAddress requires the recipient to already hold an active wallet in that currency. In a fresh sandbox they usually do not, so toAddress is the reliable choice for a first run.

10. Approve

POST /v1/users/{userId}/smart-wallets/proposals/{proposalId}/approve

No body. status moves to PENDING_SIGNATURES once the threshold is met.

11. Sign and send

Fetch the payload:

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

Sign hashToSign — a raw 32-byte digest, with no prefix. This is the opposite of step 3.

// signingKey.sign(), NOT signMessage() — no EIP-191 prefix here.
const signature = wallet.signingKey.sign(signPayload.hashToSign).serialized

from eth_account import Account

signed = Account.unsafe_sign_hash(
    bytes.fromhex(sign_payload["hashToSign"][2:]),
    OWNER_PRIVATE_KEY,
)
signature = "0x" + signed.signature.hex()

digest, _ := hex.DecodeString(strings.TrimPrefix(signPayload.HashToSign, "0x"))

// Sign the digest directly — no TextHash, no prefix.
sig, _ := crypto.Sign(digest, key)
sig[64] += 27

signature := "0x" + hex.EncodeToString(sig)

$digest = ltrim($signPayload['hashToSign'], '0x');

// Sign the digest directly — no EIP-191 prefix.
$sig = (new EC('secp256k1'))
    ->keyFromPrivate($ownerPrivateKey)
    ->sign($digest, ['canonical' => true]);

$signature = '0x'
    . str_pad(gmp_strval($sig->r->toString(), 16), 64, '0', STR_PAD_LEFT)
    . str_pad(gmp_strval($sig->s->toString(), 16), 64, '0', STR_PAD_LEFT)
    . dechex($sig->recoveryParam + 27);

Using the message-signing method here produces a signature that recovers to a different address, and the backend rejects it.

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

Expected result

GET /v1/users/{userId}/smart-wallets/proposals/{proposalId} reports status progressing PENDING_SIGNATURES → COMPLETED. The balance on the sending wallet drops by 25. If the signature is rejected, check you used signTransactionHash and not signMessage, then work through Why your signature is rejected.

The two signatures, side by side

Worth keeping in front of you.

	Step 3 — owner proof	Step 11 — proposal
What you sign	The challenge text	A 32-byte digest
EIP-191 prefix	Yes	No
TypeScript	`wallet.signMessage(msg)`	`wallet.signingKey.sign(hash).serialized`
Python	`Account.sign_message(encode_defunct(text=…))`	`Account.unsafe_sign_hash(digest, key)`
Go	`crypto.Sign(accounts.TextHash(msg), key)`	`crypto.Sign(digest, key)`
PHP	prefix, then `Keccak::hash`, then `sign`	`sign` the digest directly

Both produce a 0x-prefixed 130-character hex signature. In Go and PHP, remember v comes back as 0/1 and Ethereum expects 27/28 — add 27, as the snippets do.

Building a mobile client rather than a backend? bmoni_embedded_sdk wraps both of these as signMessage and signTransactionHash, with the key held in Android Keystore or the iOS Secure Enclave. See SDK signing.

Sandbox test data — the personas and the matching rule.
Sign a proposal — the full signing reference and a reproducible test vector.
Errors and status codes — every error these calls return.
Webhooks and events — replacing the polling in step 8.
Request test tokens — funding the wallet before step 9.

Last reviewed: 7 August 2026.

Start here

AI integration

Quickstart — zero to first send

Before you start

1. Create the user

2. Submit the KYC profile

3. Prove you control the owner address

4. Create the smart wallet

5. Start onboarding

6, 7, 8. Upload the documents

9. Create the transfer proposal

10. Approve

11. Sign and send

Expected result

The two signatures, side by side

​Before you start

​1. Create the user

​2. Submit the KYC profile

​3. Prove you control the owner address

​4. Create the smart wallet

​5. Start onboarding

​6, 7, 8. Upload the documents

​9. Create the transfer proposal

​10. Approve

​11. Sign and send

​Expected result

​The two signatures, side by side

​Related

Before you start

1. Create the user

2. Submit the KYC profile

3. Prove you control the owner address

4. Create the smart wallet

5. Start onboarding

6, 7, 8. Upload the documents

9. Create the transfer proposal

10. Approve

11. Sign and send

Expected result

The two signatures, side by side

Related