Skip to main content
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"
  }
}
Use this path when your users connect a wallet instead of verifying by email OTP. The wallet must sign the challenge from Wallet challenge.
​
x-api-key
string
required
Your StarkFi API key.
​
wallet
string
required
Wallet address that signed the challenge.
​
message
string
required
Exact challenge message returned by POST /security/wallet/challenge.
​
signed_bytes
string
required
Signature bytes (base58 for Solana, hex for EVM) proving ownership of wallet.
​
email
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"
  }
}

​
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). 
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,
  }),
});
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.