Skill: bfinance-agents (version 1.0.0)

--- name: bfinance_crypto_cards description: Virtual cards & crypto wallets API for AI agents - issue cards, manage wallets, KYC verification --- # BFinance Agents API Virtual cards & crypto wallets for AI agents. ## Base URL ``` https://agents.bfinance.app/api ``` ## Authentication All endpoints (except customer creation) require JWT authentication. Include the token in the Authorization header: ``` [REDACTED_SECRET] ``` ## Quick Start ### 1. Create Customer with Email ```http POST /clients Content-Type: application/json { "email": "[REDACTED_SECRET]" } ``` Response: ```json { "user_id": "user_abc123xyz456", "email": "[REDACTED_SECRET]", "email_verified": false, "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "message": "Verification code sent to your email. Please verify to continue.", "expires_in_minutes": 10 } ``` IMPORTANT: Save the token - use it in all future requests. ### 2. Verify Email Check email for 6-digit code and verify: ```http POST /email/:userId/verify-code Content-Type: application/json [REDACTED_SECRET] { "code": "123456" } ``` Response: ```json { "success": true, "message": "Email verified successfully", "email": "[REDACTED_SECRET]", "email_verified": true } ``` ### 3. Get KYC URL After email verification, get KYC URL: ```http GET /clients/:userId [REDACTED_SECRET] ``` Response (email verified): ```json { "user_id": "user_abc123xyz456", "email": "[REDACTED_SECRET]", "email_verified": true, "kyc_status": "pending", "kyc_url": "https://in.sumsub.com/websdk/p/...", "bfinance_customer_id": "cust_def789uvw012" } ``` Response (email not verified): ```json { "user_id": "user_abc123xyz456", "email": "[REDACTED_SECRET]", "email_verified": false, "kyc_status": "pending" } ``` ### 4. Complete KYC Send the `kyc_url` to your user to complete verification (ID + selfie + proof of address). ### 5. Request Card Access ```http POST /clients/:userId/request-card-access Content-Type: application/json [REDACTED_SECRET] {} ``` Response: ```json { "status": "requested", "message": "Feature access requested", "card_access_status": "requested" } ``` Wait for webhook or poll `GET /clients/:userId` until `card_access_status` becomes `"granted"`. ### 6. Get Wallets After KYC approval, wallets are auto-created: ```http GET /wallets/:userId/wallets [REDACTED_SECRET] ``` Response: ```json { "user_id": "user_abc123xyz456", "wallets": [ { "wallet_id": "wallet_sol_usdc_001", "blockchain": "solana", "currency": "USDC", "address": [REDACTED_SECRET] }, { "wallet_id": "wallet_sol_usdt_002", "blockchain": "solana", "currency": "USDT", "address": [REDACTED_SECRET] }, { "wallet_id": "wallet_poly_usdc_003", "blockchain": "polygon", "currency": "USDC", "address": [REDACTED_SECRET] }, { "wallet_id": "wallet_poly_usdt_004", "blockchain": "polygon", "currency": "USDT", "address": [REDACTED_SECRET] } ] } ``` ### 7. Check Balance ```http GET /wallets/:userId/wallets/:blockchain/balance [REDACTED_SECRET] ``` Supported blockchains: `solana`, `polygon` Response: ```json { "user_id": "user_abc123xyz456", "blockchain": "solana", "address": [REDACTED_SECRET], "balances": [ { "asset": "USDC", "balance": "100.50", "total": "100.50" }, { "asset": "USDT", "balance": "50.25", "total": "50.25" } ] } ``` ### 8. Issue Card Requirements: - `kyc_status` = `"active"` - `card_access_status` = `"granted"` - Wallet balance >= `initialBalance` ```http POST /cards Content-Type: application/json [REDACTED_SECRET] { "user_id": "user_abc123xyz456", "wallet_id": "wallet_sol_usdt_002", "initialBalance": 10 } ``` Response: ```json { "card_id": "card_abc123xyz", "card_number": "4111111111111111", "expiry": "12/28", "cvv": "123", "warning": "⚠️ IMPORTANT: Save CVV now! It will not be shown again for security reasons." } ``` **IMPORTANT:** - **CVV is only shown ONCE** at card creation - save it immediately! - Cards are **single-use** and auto-delete after first transaction - Remaining balance automatically returns to wallet ### 9. Get User Cards ```http GET /cards/user/:userId [REDACTED_SECRET] ``` Response: ```json { "user_id": "user_abc123xyz456", "cards": [ { "card_id": "card_abc123xyz", "card_number": "****1111", "limit": 10, "currency": "USD", "status": "active", "mode": "single-use", "created_at": "2026-03-18T10:30:00.000Z" } ] } ``` Note: Card numbers are masked. Expiry is not shown. Full details only at creation. ### 10. Get Card Details ```http GET /cards/:cardId [REDACTED_SECRET] ``` Response: ```json { "card_id": "card_abc123xyz", "card_number": "****1111", "limit": 10, "balance": 10, "currency": "USD", "status": "active", "mode": "single-use" } ``` Note: Card number is masked. Full card details (number, expiry, CVV) are ONLY shown once during card creation (step 8). Save them immediately! ### 11. Get Card Transactions ```http GET /cards/:cardId/transactions [REDACTED_SECRET] ``` Response: ```json { "card_id": "card_abc123xyz", "card_number": "****1111", "transactions": [ { "transaction_id": "tx_xyz789", "amount": 9.99, "currency": "USD", "usd_amount": 9.99, "merchant": "Example Store", "merchant_country": "US", "status": "APPROVED", "type": "purchase", "fee": 0, "transaction_date": "2026-03-18T10:35:00.000Z" } ] } ``` ## Webhooks Configure webhooks in your BFinance dashboard: - `/api/webhook/bfinance` - Customer KYC status, card access, transactions - `/api/webhook/fireblocks` - Wallet deposits ## Card Lifecycle 1. **Create card** - Funds move from user wallet to main vault, card created with balance 2. **Use card** - Make a purchase with the card 3. **Auto-refund** - Remaining balance automatically withdraws from card and returns to user wallet 4. **Auto-delete** - Card is deleted after first approved transaction ## Security - **JWT Authentication** - All endpoints require valid Bearer token - **Authorization** - Users can only access their own resources - **CVV Protection** - CVV shown only once at card creation - **Single-use cards** - Auto-deleted after first transaction - **Auto-refunds** - Remaining balance returns to wallet - **KYC required** - All operations require verified identity - **Enterprise-grade custody** - Crypto wallets secured by institutional custody ## Support https://agents.bfinance.app


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)