---
name: bfinance_agents
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:
```
Authorization: Bearer YOUR_JWT_TOKEN
```

## Quick Start

### 1. Create Customer with Email
```bash
curl -X POST https://agents.bfinance.app/api/clients \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
```

Response:
```json
{
  "user_id": "user_abc123xyz456",
  "email": "user@example.com",
  "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:
```bash
curl -X POST https://agents.bfinance.app/api/email/USER_ID/verify-code \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"code": "123456"}'
```

Response:
```json
{
  "success": true,
  "message": "Email verified successfully",
  "email": "user@example.com",
  "email_verified": true
}
```

### 3. Get KYC URL
After email verification, get KYC URL:
```bash
curl https://agents.bfinance.app/api/clients/USER_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

Response (email verified):
```json
{
  "user_id": "user_abc123xyz456",
  "email": "user@example.com",
  "email_verified": true,
  "kyc_status": "pending",
  "kyc_url": "https://in.sumsub.com/websdk/p/..."
}
```

Response (email not verified):
```json
{
  "user_id": "user_abc123xyz456",
  "email": "user@example.com",
  "email_verified": false,
  "kyc_status": "pending"
}
```

### 4. Complete KYC
Send the `kyc_url` to your user to complete verification (ID + selfie + proof of address).

After KYC approval:
- Wallets are automatically created (Solana & Polygon USDC/USDT)
- Card access is automatically requested
- Wait for `card_access_status` to become `"granted"`

### 5. Get Wallets
After KYC approval, wallets are auto-created:
```bash
curl https://agents.bfinance.app/api/wallets/USER_ID/wallets \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

Response:
```json
{
  "user_id": "user_abc123xyz456",
  "wallets": [
    {
      "wallet_id": "wallet_sol_usdc_001",
      "blockchain": "solana",
      "currency": "USDC",
      "address": "ExampleSolanaAddress1234567890ABCDEFGHabcdefgh"
    },
    {
      "wallet_id": "wallet_sol_usdt_002",
      "blockchain": "solana",
      "currency": "USDT",
      "address": "ExampleSolanaAddress1234567890ABCDEFGHabcdefgh"
    },
    {
      "wallet_id": "wallet_poly_usdc_003",
      "blockchain": "polygon",
      "currency": "USDC",
      "address": "0x0000000000000000000000000000000000000000"
    },
    {
      "wallet_id": "wallet_poly_usdt_004",
      "blockchain": "polygon",
      "currency": "USDT",
      "address": "0x0000000000000000000000000000000000000000"
    }
  ]
}
```

### 6. Check Balance
```bash
curl https://agents.bfinance.app/api/wallets/USER_ID/wallets/BLOCKCHAIN/balance \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

Supported blockchains: `solana`, `polygon`

Response:
```json
{
  "user_id": "user_abc123xyz456",
  "blockchain": "solana",
  "address": "ExampleSolanaAddress1234567890ABCDEFGHabcdefgh",
  "balances": [
    {
      "asset": "USDC",
      "balance": "100.50",
      "total": "100.50"
    },
    {
      "asset": "USDT",
      "balance": "50.25",
      "total": "50.25"
    }
  ]
}
```

### 7. Issue Card
Requirements:
- `kyc_status` = `"active"`
- `card_access_status` = `"granted"`
- Wallet balance >= `initialBalance`

```bash
curl -X POST https://agents.bfinance.app/api/cards \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "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

### 8. Get User Cards
```bash
curl https://agents.bfinance.app/api/cards/user/USER_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

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.

### 9. Get Card Details
```bash
curl https://agents.bfinance.app/api/cards/CARD_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

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 7). Save them immediately!

### 10. Get Card Transactions
```bash
curl https://agents.bfinance.app/api/cards/CARD_ID/transactions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

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