For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
RegisterLoginSandbox Login
GuidesRecipesAPI Reference
GuidesRecipesAPI Reference
  • Product Overview
    • Products & Features
    • Key Concepts
  • Getting Started
    • Account Setup
    • Quickstart
  • Checkout
    • Settlement Locations
  • Payouts
    • Payout Overview
    • What is a Payout
      • Identifying Users by Internal User ID
        • Identifying Users by Wallet
  • Subscriptions
    • Subscriptions Overview
  • Marketplaces
    • Marketplace Overview
    • How Marketplaces Work
    • Marketplaces Webhooks
    • Marketplaces Implementation
  • Developer Resources
    • Custom Branding
    • Checkout Implementation
    • Webhooks
  • Merchant Dashboard
    • Login & Account Access
    • Users and Roles
    • Rate Limits
    • Developer Contact
LogoLogo
RegisterLoginSandbox Login
On this page
  • Overview
  • When to Use Wallet-Based Identification
  • Implementation
  • Example API Call
  • Supported Blockchains
  • Payout Flows Using Wallet Identification
  • User Self-Custodial Wallet Payouts
  • Merchant BYO Wallet Payouts (with Wallet IDs)
  • Common Questions
PayoutsUser IdentificationAdvanced

Users With Crypto Wallets

Was this page helpful?
Previous

Payout Scenarios

Next
Built with

This page is for advanced / cryptocurrency-native companies. If that’s not you, head back to the Quickstart for the standard flows.

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

  • Gaming platforms 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 Identifying Users by Internal User ID

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
  • Stellar - XLM, USDC
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: 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.