Integration guide

Everything you need to build a wallet system on TOKOPAY: authenticate, provision users, derive multi-chain addresses, move funds, and reconcile billing. Base URL is your deployment host.

1. Get an API key

In API Keys, create a key and choose its permissions — Read (queries), Write (create users/wallets, transfers), Contract (raw calls). Use a Read-write key for most backends. The secret (ws_live_…) is shown once — store it server-side.

Authorization: Bearer ws_live_xxxxxxxx...

2. Create a user

Each end user gets their own encrypted HD seed automatically. Pass your own externalId so you can map it back.

curl -X POST https://api.tokopay.io/api/v1/users \
  -H "Authorization: Bearer ws_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "your-user-123", "label": "alice@app.com" }'

# → { "id": "ckuser...", "externalId": "your-user-123" }

3. Discover networks & derive a wallet

List the networks available to you, then derive an address for a user on one. EVM and Solana both derive from that user's single seed.

curl https://api.tokopay.io/api/v1/networks -H "Authorization: Bearer ws_live_..."
# pick a network "id", then:

curl -X POST https://api.tokopay.io/api/v1/wallets \
  -H "Authorization: Bearer ws_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "userId": "ckuser...", "chainId": "ckNetworkId..." }'

# → { "wallet": { "id": "ckw...", "address": "0x...", "derivationPath": "m/44'/60'/0'/0/0" } }

4. Check balances

# native balance
curl "https://api.tokopay.io/api/v1/wallets/balance?walletId=ckw..." -H "Authorization: Bearer ws_live_..."
# ERC-20 token balance
curl "https://api.tokopay.io/api/v1/wallets/token-balance?walletId=ckw...&contract=0x..." -H "Authorization: Bearer ws_live_..."

5. Move funds

Native, tokens (listed by id or a custom contract), NFTs, and SPL all use the same shape. Keys never leave the server — you authorize the action, we sign.

# native
POST /api/v1/wallets/send { "walletId", "to", "amount" }

# ERC-20 / SPL (listed token by id, or custom contract/mint)
POST /api/v1/wallets/transfer-token
{ "walletId", "to", "amount", "tokenId" }            # listed
{ "walletId", "to", "amount", "contract", "decimals" } # custom EVM
{ "walletId", "to", "amount", "mint" }                 # custom Solana

# NFTs
POST /api/v1/wallets/transfer-nft
{ "walletId", "to", "tokenId", "standard": "ERC721", "contract" }

# arbitrary contract call (needs Contract permission + tenant feature)
POST /api/v1/wallets/contract-call
{ "walletId", "to", "abi": ["function mint(address,uint256)"], "method": "mint", "args": ["0x...", 1] }

6. Per-user sign-in (Google)

Send your users to Google sign-in; on return they're provisioned with a seed and a login is recorded. Mint a scoped ws_usr_… token for their session from your server.

GET /api/auth/google?tenant=YOUR_SLUG

7. Billing & your wallet

The first 100 active users each month are free; beyond that you're charged per active user and per transaction, deducted from your prepaid balance. Fund it from Wallet — each of your billing deposit addresses (EVM + Solana) accepts the platform's settlement token (USDC/USDT). View charges in Billing.

Errors

401 invalid token · 403 insufficient permission or disabled feature · 404 not found · 422 unsupported op · 502 chain/RPC failure. Bodies are { "error": "...", "detail"?: "..." }.