Prepare KYC (wallet)

curl --request POST \
  --url https://api.starkfi.io/kyc/prepare-wallet \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "wallet": "FmTGYpzX27fDqaiytXUdFVaphC5o68G61Q3uhVM2d8bm",
    "message": "<challenge_message>",
    "signed_bytes": "<signature>"
  }'

{
  "statusCode": 201,
  "success": true,
  "status": "user_prepared",
  "message": "User prepared for KYC via wallet",
  "data": {
    "email_verified": false,
    "wallet_verified": true,
    "kyc_approved": false,
    "kyc_status": "pending"
  }
}

{
  "statusCode": 200,
  "success": true,
  "status": "user_already_prepared",
  "message": "User prepared for KYC via wallet",
  "data": {
    "email_verified": false,
    "wallet_verified": true,
    "kyc_approved": false,
    "kyc_status": "pending"
  }
}

{
  "statusCode": 401,
  "success": false,
  "status": "invalid_signature",
  "message": "KYC wallet prepare failed"
}

{
  "statusCode": 409,
  "success": false,
  "status": "wallet_already_linked",
  "message": "KYC wallet prepare failed"
}

POST

kyc

prepare-wallet

curl --request POST \
  --url https://api.starkfi.io/kyc/prepare-wallet \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "wallet": "FmTGYpzX27fDqaiytXUdFVaphC5o68G61Q3uhVM2d8bm",
    "message": "<challenge_message>",
    "signed_bytes": "<signature>"
  }'

{
  "statusCode": 201,
  "success": true,
  "status": "user_prepared",
  "message": "User prepared for KYC via wallet",
  "data": {
    "email_verified": false,
    "wallet_verified": true,
    "kyc_approved": false,
    "kyc_status": "pending"
  }
}

{
  "statusCode": 200,
  "success": true,
  "status": "user_already_prepared",
  "message": "User prepared for KYC via wallet",
  "data": {
    "email_verified": false,
    "wallet_verified": true,
    "kyc_approved": false,
    "kyc_status": "pending"
  }
}

{
  "statusCode": 401,
  "success": false,
  "status": "invalid_signature",
  "message": "KYC wallet prepare failed"
}

{
  "statusCode": 409,
  "success": false,
  "status": "wallet_already_linked",
  "message": "KYC wallet prepare failed"
}

Use this path when your users connect a wallet instead of verifying by email OTP. The wallet must sign the challenge from Wallet challenge.

string

required

Your StarkFi API key.

string

required

Wallet address that signed the challenge.

string

required

Exact challenge message returned by POST /security/wallet/challenge.

string

required

Signature bytes (base58 for Solana, hex for EVM) proving ownership of wallet.

string

Optional email to link to the wallet. If provided, it must not already belong to a different wallet.

curl --request POST \
  --url https://api.starkfi.io/kyc/prepare-wallet \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "wallet": "FmTGYpzX27fDqaiytXUdFVaphC5o68G61Q3uhVM2d8bm",
    "message": "<challenge_message>",
    "signed_bytes": "<signature>"
  }'

{
  "statusCode": 201,
  "success": true,
  "status": "user_prepared",
  "message": "User prepared for KYC via wallet",
  "data": {
    "email_verified": false,
    "wallet_verified": true,
    "kyc_approved": false,
    "kyc_status": "pending"
  }
}

{
  "statusCode": 200,
  "success": true,
  "status": "user_already_prepared",
  "message": "User prepared for KYC via wallet",
  "data": {
    "email_verified": false,
    "wallet_verified": true,
    "kyc_approved": false,
    "kyc_status": "pending"
  }
}

{
  "statusCode": 401,
  "success": false,
  "status": "invalid_signature",
  "message": "KYC wallet prepare failed"
}

{
  "statusCode": 409,
  "success": false,
  "status": "wallet_already_linked",
  "message": "KYC wallet prepare failed"
}

Signing the challenge message

After you receive data.message from Wallet challenge, sign that exact string with the user’s wallet. Send the result as signed_bytes in this request (hex for EVM, base58 for Solana).

EVM (ethers.js)
Solana (web3.js)

import { Wallet } from "ethers";

const privateKey = "YOUR_PRIVATE_KEY";
const wallet = new Wallet(privateKey);

// Exact string from POST /security/wallet/challenge → data.message
const message =
  "Prepare KYC StarkFi:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb at 1710000000000 nonce: a1b2c3... ";

const signed_bytes = await wallet.signMessage(message);

await fetch("https://api.starkfi.io/kyc/prepare-wallet", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "<api_key>",
  },
  body: JSON.stringify({
    wallet: wallet.address,
    message,
    signed_bytes,
  }),
});

import { Keypair } from "@solana/web3.js";
import bs58 from "bs58";
import nacl from "tweetnacl";

const privateKeyBase58 = "YOUR_PRIVATE_KEY_BASE58";
const keypair = Keypair.fromSecretKey(bs58.decode(privateKeyBase58));

// Exact string from POST /security/wallet/challenge → data.message
const message =
  "Prepare KYC StarkFi:FmTGYpzX27fDqaiytXUdFVaphC5o68G61Q3uhVM2d8bm at 1710000000000 nonce: a1b2c3... ";

const messageBytes = new TextEncoder().encode(message);
const signature = nacl.sign.detached(messageBytes, keypair.secretKey);
const signed_bytes = bs58.encode(signature);

await fetch("https://api.starkfi.io/kyc/prepare-wallet", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "<api_key>",
  },
  body: JSON.stringify({
    wallet: keypair.publicKey.toBase58(),
    message,
    signed_bytes,
  }),
});

In the browser, use your wallet adapter’s signMessage (EVM: personal_sign via ethers or the provider; Solana: sign the UTF-8 bytes and base58-encode the signature). With a provider like Privy, you can sign without exposing private keys in your app.

After a successful prepare, call Create KYC session with wallet instead of email.

Wallet challenge Validate email

Overview

Guides

Signing the challenge message

​Signing the challenge message

Signing the challenge message