PayoutsUser Identification

Users With Crypto Wallets

Overview

When users control their own crypto wallets, Coinflow uses the wallet address as their unique identifier. This eliminates the need for separate account systems and enables seamless Web3 experiences where users connect their wallets and cash out directly.

When to Use Wallet-Based Identification

Perfect For

Use wallet addresses when your users own crypto wallets

  • DeFi platforms - Users with on-chain balances
  • Web3 gaming - Players with NFTs and in-game tokens
  • NFT marketplaces - Creators and collectors with wallets
  • DAO treasuries - Members managing on-chain funds
  • Crypto reward programs - Users earning directly to wallets

User flow: Connect wallet → Complete KYC → Link bank → Withdraw

Use User IDs Instead

These scenarios require internal user IDs

  • Traditional gaming - Users with internal credit systems
  • Marketplaces managing balances - You track seller earnings
  • Reward programs - Internal point systems
  • No Web3 infrastructure - Users don’t have wallets
  • Merchant-initiated payouts - You control disbursement timing

→ See Users Without Crypto Wallets

Key Decision Factor: Who Controls the Funds?

If users control their own crypto wallets and balances, use wallet-based identification. If you manage user balances internally (database, internal ledger), use user ID-based identification. See Understanding Payout Flows for more details.

Implementation

When using the API, pass the wallet address in the appropriate field:

  • For session keys: Use x-coinflow-auth-wallet header
  • For user identification: The wallet address serves as the unique identifier
  • For transactions: User must sign messages/transactions with their wallet

Example API Call

$curl --request POST \
>  --url https://api-sandbox.coinflow.cash/api/withdraw/kyc \
>  --header 'Authorization: YOUR_API_KEY' \
>  --header 'x-coinflow-auth-wallet: 5Fn8...vFb7' \
>  --header 'Content-Type: application/json' \
>  --data '{
>    "email": "user@example.com",
>    "country": "US"
>  }'

Supported Blockchains

Coinflow supports wallet identification across multiple blockchain networks:

Supported Networks
  • Solana - SOL, USDC, USDT
  • Ethereum - ETH, USDC, USDT
  • Base - ETH, USDC
  • Polygon - MATIC, USDC, USDT
  • Arbitrum - ETH, USDC, USDT
Wallet Requirements
  • User must be able to sign messages
  • For self-custodial payouts: Sufficient token balance
  • Gas fees required (unless using gasless transactions)
  • Wallet must support the blockchain’s signature standard

Payout Flows Using Wallet Identification

User Self-Custodial Wallet Payouts

Users withdraw directly from their own wallets:

  1. User connects wallet - Signs message to authenticate
  2. Complete KYC - One-time identity verification
  3. Link bank account - Add destination for fiat funds
  4. Initiate withdrawal - User signs transaction to approve withdrawal
  5. Funds transfer - Crypto converted to fiat, deposited to bank

→ See User Self-Custodial Wallet Payouts for implementation details

Merchant BYO Wallet Payouts (with Wallet IDs)

Merchants can use wallet addresses to identify users even when paying from merchant wallets:

  1. Track user wallet addresses - Store each user’s wallet
  2. Merchant initiates payout - Using user’s wallet address as identifier
  3. Funds disbursed - From your wallet, identified by their wallet address

→ See Merchant Payout from BYO Wallet

Common Questions

Q: Can I use wallet addresses with Coinflow-managed wallets? A: Typically no. Coinflow In-App Wallets are designed for user ID-based identification. If you want wallet-based IDs, use user self-custodial or merchant BYO wallet flows.

Q: What if a user has multiple wallets? A: Each wallet address is treated as a separate identity. You can associate multiple wallets with a single user in your system by calling the API with additionalWallets parameter.

Q: Do users need gas fees? A: For user self-custodial withdrawals, yes (unless using gasless EVM USDC). For merchant-initiated payouts, the merchant covers gas fees.

Q: Can users change their wallet? A: Users can link additional wallets, but each wallet creates a separate Coinflow identity. The original wallet-to-bank link remains tied to that specific wallet address.