Integration & Monitoring

Supported Features

Check available options for stablecoin operations:

Supported Countries

GET /supported/countries

List all countries where users can onboard and use stablecoin services.

Response includes:

Country code and name
Individual support (true/false)
Corporate support (true/false)

Supported Chains

GET /supported/chains

List all blockchain networks available for stablecoin operations.

Returns: ["polygon", "ethereum", "solana", "base", "arbitrum", "optimism", "celo", "tron", "bsc", "avalanche"]

Supported Currencies

GET /supported/currencies

List all fiat and stablecoin currencies supported.

Includes: Currency name and label for both fiat (EUR, GBP, USD) and stablecoin (USDC, USDT, etc.)

Supported Banks

Get the list of supported banks for remittance destinations by currency:

Endpoint: GET /banks/?currency={currency}

GET /banks/?currency=PKR

Response:

[
  {
    "name": "Easypaisa",
    "code": "EASYPAISA",
    "accountType": "DW"
  },
  {
    "name": "National Bank of Pakistan",
    "code": "NBP",
    "accountType": "BA"
  }
]

Account Types:

BA: Bank Account
DW: Digital Wallet (e.g., mobile wallets)

Usage Example:

// User selects Pakistan as destination
const banks = await bakkt.getBanks('PKR');

// Display dropdown of available banks
banks.forEach(bank => {
  console.log(`${bank.name} (${bank.code}) - ${bank.accountType === 'DW' ? 'Mobile Wallet' : 'Bank Account'}`);
});

// User selects bank
const selectedBank = banks.find(b => b.code === 'EASYPAISA');
// Use this bank_code when creating remote bank account

Use these to:

Build dynamic UI showing available options
Validate user selections before API calls
Display supported chains/currencies to users

Example:

// Check if user's country is supported
const countries = await bakkt.onofframp.getSupportedCountries();
const userCountry = countries.find(c => c.country_code === 'NG');

if (userCountry.is_individual_supported) {
  console.log('Nigeria is supported for individuals ✓');
}

// Get available chains for wallet creation
const chains = await bakkt.onofframp.getSupportedChains();
console.log('Available chains:', chains);
// ["polygon", "ethereum", "solana", ...]

Transaction Monitoring

Get Transaction History

Endpoint: GET /stablecoin/user/transactions

View all user transactions. Returns complete history of conversions with status, amounts, and transaction IDs.

curl --request GET \
     --url 'https://api.bakkt.com/stablecoin/user/transactions' \
     --header 'Authorization: API-Key YOUR_API_KEY' \
     --header 'user-uuid: YOUR_USER_UUID'

Get Detailed Transaction Status

Endpoint: GET /stablecoin/process/

Look up transaction details by process UUID. Get complete status information for any stablecoin conversion transaction.

curl --request GET \
     --url 'https://api.bakkt.com/stablecoin/process/?process_uuid=5594401c-0072-4df2-be9c-d491c0754c21' \
     --header 'Authorization: API-Key YOUR_API_KEY'

Response:

{
  "status": "PROCESS_COMPLETED",
  "direction": "cryptoToFiat",
  "input": {
    "amount": 1000,
    "currency": "USDC",
    "transaction_id": "0xabc..."
  },
  "output": {
    "amount": 950,
    "currency": "EUR",
    "transaction_id": "iban-transfer-uuid"
  }
}

Use process UUID from webhooks to query detailed transaction information.

Transaction Statuses

Track your conversion transactions through these statuses:

Status	Meaning	Next Step
`CRYPTO_TRANSFER_ISSUED`	Stablecoin deposit detected	Wait for confirmations
`CRYPTO_TRANSFER_COMPLETED`	Stablecoin confirmed on-chain	Conversion starting
`WAITING_FOR_FINALITY`	Waiting for block finality	Automatic
`FINALITY_REACHED`	Safe to convert	Conversion in progress
`IBAN_TRANSFER_ISSUED`	Fiat transfer initiated	Wait for bank
`PROCESS_COMPLETED`	✅ Complete	Fiat in bank account
`ON_HOLD_KYC`	KYC required	Complete KYC
`PROCESS_BLOCKED`	Manual review needed	Contact support

Warning: Transactions can be held if KYC is incomplete or if they trigger AML checks. Ensure users complete KYC before transacting.

Webhooks

Receive real-time updates on stablecoin to fiat conversion transactions and bank account statuses.

Note: Webhook Setup: Configure your webhook URL and secret using the PATCH /merchant endpoint. See the Onboarding guide for setup instructions.

Fiat-to-Stablecoin Webhooks

Receive updates when users convert fiat to stablecoins:

Event Type	subType	Description
`fiatToCrypto`	`PENDING`	Transaction created, awaiting processing
`fiatToCrypto`	`IN_PROGRESS`	Fiat received, processing stablecoin transfer
`fiatToCrypto`	`CRYPTO_TRANSFER_ISSUED`	Stablecoin sent to network (includes `transactionHash`)
`fiatToCrypto`	`SUCCESS`	Transaction complete
`fiatToCrypto`	`ON_HOLD`	Held for KYC or AML review
`fiatToCrypto`	`FAILED`	Transaction failed
`fiatToCrypto`	`REFUNDED`	Transaction refunded to customer

Example Payload:

{
  "type": "fiatToCrypto",
  "subType": "SUCCESS",
  "uuid": "user-uuid",
  "data": {
    "status": "SUCCESS",
    "transactionUuid": "txn-uuid",
    "direction": "fiatToCrypto",
    "amountFiat": 100.00,
    "amountCrypto": 100.5,
    "currencyFiat": "EUR",
    "currencyCrypto": "USDC",
    "walletAddress": "0x...",
    "transactionHash": "0x...",
    "fees": 1.5
  }
}

Stablecoin-to-Fiat Webhooks

Receive updates when users convert stablecoins to fiat:

Event Type	subType	Description
`cryptoToFiat`	`PENDING`	Transaction created
`cryptoToFiat`	`IN_PROGRESS`	Stablecoin received, processing fiat transfer
`cryptoToFiat`	`FIAT_TRANSFER_ISSUED`	Fiat transfer initiated (includes `amountFiat`)
`cryptoToFiat`	`SUCCESS`	Fiat delivered to bank account
`cryptoToFiat`	`ON_HOLD`	Held for KYC or AML review
`cryptoToFiat`	`FAILED`	Transaction failed
`cryptoToFiat`	`LIMIT_BREACHED`	Amount below minimum (no transaction created)
`cryptoToFiat`	`REFUNDED`	Transaction refunded to customer

Example Payload:

{
  "type": "cryptoToFiat",
  "subType": "SUCCESS",
  "uuid": "user-uuid",
  "data": {
    "status": "SUCCESS",
    "transactionUuid": "txn-uuid",
    "direction": "cryptoToFiat",
    "amountCrypto": 100.5,
    "amountFiat": 98.00,
    "currencyCrypto": "USDC",
    "currencyFiat": "EUR",
    "transactionHash": "0x...",
    "remoteBankAccountUuid": "bank-uuid",
    "chain": "Polygon",
    "fees": 2.5,
    "beneficiaryDetails": {
      "receiverName": "John Doe",
      "accountDetails": {
        "iban": "DE89...",
        "bic": "DEUTDEFF",
        "account_name": "ALIAS"
      }
    }
  }
}

Bank Account Status Webhooks

Receive updates on stablecoin fiat account creation:

Event Type	subType	Description
`bakktBankAccount`	`statusUpdate`	Stablecoin fiat account status changed (check `data.status`)

Possible stablecoin fiat account statuses:

WAITING_CREATION - Stablecoin fiat account creation in progress
ACTIVE - Stablecoin fiat account ready to receive deposits
FAILED_CREATION - Stablecoin fiat account creation failed (check error)
DISABLED - Stablecoin fiat account disabled

Example Payload:

{
  "type": "bakktBankAccount",
  "subType": "statusUpdate",
  "uuid": "user-uuid",
  "data": {
    "uuid": "stablecoin-fiat-account-uuid",
    "currency": "EUR",
    "bank_country": "DE",
    "iban": "DE89...",
    "bic": "DEUTDEFF",
    "status": "ACTIVE"
  }
}

Transaction Hold Reasons

When subType is ON_HOLD, check data.status for the specific reason:

ON_HOLD_KYC - User needs to complete KYC verification
ON_HOLD_PROCESS - Transaction under AML review (typically 1-24 hours)

Once the hold is cleared, the transaction will automatically resume processing.

Query Parameters

Wallet Endpoint Query Params

GET /stablecoin/user/wallet/polygon?remote_bank_account_uuid=abc-123

remote_bank_account_uuid (optional): Link wallet to a specific remote bank account for automatic routing.

Fee Calculator

Calculate exact fees for stablecoin conversion operations:

Endpoint: GET /stablecoin/fees/

Get detailed fee breakdown for any stablecoin-to-fiat or fiat-to-stablecoin conversion.

curl --request GET \
     --url 'https://api.bakkt.com/stablecoin/fees/?payment_method=bank_transfer&direction=cryptoToFiat&input_currency=USDC&output_currency=EUR&amount=1000' \
     --header 'Authorization: API-Key YOUR_API_KEY'

Response:

{
  "bakkt_fee": 0.005,
  "merchant_fee": {
    "type": "add",
    "amount": 0.002
  },
  "total_fee_percentage": 0.007
}

Example Usage:

// Calculate fees before conversion
const fees = await bakkt.onofframp.calculateFees({
  payment_method: 'bank_transfer',
  direction: 'cryptoToFiat',
  input_currency: 'USDC',
  output_currency: 'EUR',
  amount: 1000
});

const outputAmount = 1000 * (1 - fees.total_fee_percentage);
console.log(`Convert 1000 USDC → Receive ${outputAmount.toFixed(2)} EUR after fees`);

Best Practices

Remote Bank Account Setup

Add remote bank account before user sends stablecoins
- Verify bank details are correct (typos cause payment failures)
- Set main_recipient: true for primary account
- For INR, include swift_code, bank_name, recipient_relationship, and remittance_purpose in account_details (see API reference); do not put customer_details under account_details for INR. For PKR, follow the current API reference for account_details.

Wallet Address Management

Display clear instructions on which tokens are supported
- Show minimum deposit amounts
- For Solana, warn about rent-exempt requirement
- Provide transaction hash for user tracking

Transaction Monitoring

Implement webhook handlers for all transaction statuses
- Show real-time status updates to users
- Provide estimated settlement times
- Handle edge cases (holds, failures, refunds)

Sandbox Testing

# Test wallet creation (all chains available)
curl -X GET 'https://sandbox.api.bakkt.com/stablecoin/user/wallet/polygon' \
     -H 'Authorization: API-Key YOUR_KEY' -H 'user-uuid: USER_UUID'

curl -X GET 'https://sandbox.api.bakkt.com/stablecoin/user/wallet/solana' \
     -H 'Authorization: API-Key YOUR_KEY' -H 'user-uuid: USER_UUID'

curl -X GET 'https://sandbox.api.bakkt.com/stablecoin/user/wallet/base' \
     -H 'Authorization: API-Key YOUR_KEY' -H 'user-uuid: USER_UUID'

# Test remote bank account creation (returns receiving_address)
curl -X POST 'https://sandbox.api.bakkt.com/stablecoin/user/bank-account/remote' \
     -H 'Authorization: API-Key YOUR_KEY' \
     -H 'bakkt-session-id: SESSION_ID' \
     -H 'Content-Type: application/json' \
     -d '{"account_name":"Test","main_recipient":true,"account_details":{"currency":"EUR","iban":"DE89370400440532013000"}}'

Next Steps

View Full API Reference

Explore all 9 endpoints with interactive examples

Accounts API

Send money to third-party remote bank accounts internationally

Transaction Status Guide

Understand all possible transaction statuses (coming soon)

Webhook Integration

Set up real-time transaction notifications (coming soon)