Developer Quickstart

Get started with Banking Genius API in under 5 minutes.

Step 1: Choose a Wallet Address

Your wallet address is your API key. Pick any unique string:

WALLET_ADDRESS="my-company-wallet-prod"

Tip: Use something unique to your application. No signup required.

Step 2: Top Up Your Wallet

Add credits to your wallet. In dev mode, use the free topup endpoint:

curl -X POST http://localhost:3000/api/wallet/topup \
  -H "Content-Type: application/json" \
  -d '{"address": "my-company-wallet-prod", "amount": 1000}'

This adds 1000 credits (worth $1.00) to your wallet.

Step 3: Make Your First API Call

Call any banking endpoint with your wallet as a bearer token:

curl -H "Authorization: Bearer my-company-wallet-prod" \
  http://localhost:3000/api/banking/rates

Expected Response

{
  "base": "USD",
  "timestamp": "2024-01-15T10:30:00Z",
  "rates": {
    "EUR": 0.92,
    "GBP": 0.79,
    "CZK": 23.50,
    "JPY": 148.50,
    ...
  }
}

Step 4: Check Your Balance

Verify credits were deducted:

curl -H "Authorization: Bearer my-company-wallet-prod" \
  http://localhost:3000/api/wallet/balance

Integration Examples

Node.js / JavaScript

const WALLET = 'my-company-wallet-prod';
const API_BASE = 'http://localhost:3000';

async function getExchangeRates() {
  const response = await fetch(`${API_BASE}/api/banking/rates`, {
    headers: { 'Authorization': `Bearer ${WALLET}` }
  });

  if (response.status === 402) {
    // Handle payment required - need more credits
    const error = await response.json();
    console.log('Need to top up:', error.payment);
    return null;
  }

  return response.json();
}

// Usage
const rates = await getExchangeRates();
console.log('EUR rate:', rates.rates.EUR);
console.log('GBP rate:', rates.rates.GBP);

Python

import requests

WALLET = 'my-company-wallet-prod'
API_BASE = 'http://localhost:3000'

def get_exchange_rates():
    response = requests.get(
        f'{API_BASE}/api/banking/rates',
        headers={'Authorization': f'Bearer {WALLET}'}
    )

    if response.status_code == 402:
        # Handle payment required
        error = response.json()
        print(f"Need to top up: {error['payment']}")
        return None

    return response.json()

# Usage
rates = get_exchange_rates()
print(f"EUR rate: {rates['rates']['EUR']}")
print(f"GBP rate: {rates['rates']['GBP']}")

cURL / Shell Script

#!/bin/bash
WALLET="my-company-wallet-prod"
API_BASE="http://localhost:3000"

# Check balance
curl -s -H "Authorization: Bearer $WALLET" "$API_BASE/api/wallet/balance" | jq

# Get rates
curl -s -H "Authorization: Bearer $WALLET" "$API_BASE/api/banking/rates" | jq '.rates.EUR'

# Convert 100 USD to EUR
curl -s -X POST "$API_BASE/api/banking/convert" \
  -H "Authorization: Bearer $WALLET" \
  -H "Content-Type: application/json" \
  -d '{"from":"USD","to":"EUR","amount":100}' | jq

Handling HTTP 402

When you run out of credits, you'll receive a 402 response:

{
  "error": "Payment required",
  "message": "This endpoint requires 5 credits. You have 2 credits.",
  "payment": {
    "required": true,
    "amount": 5,
    "currentBalance": 2,
    "topupUrl": "/api/wallet/topup"
  }
}

Your integration should:

  1. Catch 402 responses
  2. Top up credits (or alert your system to add funds)
  3. Retry the original request

Best Practices

Next Steps