Deposits Guide

Before users can create orders or fund escrow, they need balance in their account. OFFER-HUB supports two deposit methods depending on your payment provider configuration.

Payment Providers

Set your provider in environment:

PAYMENT_PROVIDER=crypto  # or "airtm"

Crypto Deposits (Default)

When PAYMENT_PROVIDER=crypto, users deposit by sending USDC to their Stellar address.

Step 1: Get Deposit Address

curl http://localhost:4000/api/v1/users/usr_abc123/wallet/deposit \
  -H "Authorization: Bearer ohk_live_your_api_key"

Response:

{
  "data": {
    "provider": "crypto",
    "method": "stellar_address",
    "address": "GCV24WNJYXPG3QFNP6ZQMLVEMHQX5S6J2OWKGVF5U3XC6HF4QQHG7WMD",
    "asset": {
      "code": "USDC",
      "issuer": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
    },
    "network": "testnet",
    "instructions": "Send USDC to this Stellar address. Deposits are detected automatically within seconds."
  }
}

Step 2: User Sends USDC

The user sends USDC from any Stellar wallet:

• Lobstr — Mobile wallet
• StellarTerm — Web wallet
• Exchange — Coinbase, Binance, etc. (if they support Stellar USDC)

Step 3: Automatic Detection

OFFER-HUB monitors the blockchain for incoming transactions. When USDC arrives:

1. Transaction detected — Horizon streaming catches the payment
2. Balance updated — Off-chain balance incremented
3. Event emitted — balance.credited pushed over the SSE event stream
4. User notified — UI can update in real-time

Deposit Flow Diagram

AirTM Deposits

With AirTM credentials configured, users can fund their accounts through AirTM's payment network. AirTM is not selected through PAYMENT_PROVIDER — that variable must stay crypto.

For the complete server-side flow — user linking, the create request, confirmationUri, statuses, and webhook delivery — see the AirTM Provider Guide.

Step 1: Create Top-up Request

curl -X POST http://localhost:4000/api/v1/topups \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440009" \
  -d '{
    "userId": "usr_abc123",
    "amount": "100.00",
    "currency": "USD"
  }'

Response:

{
  "data": {
    "id": "top_xyz789",
    "userId": "usr_abc123",
    "amount": "100.00",
    "currency": "USD",
    "status": "pending",
    "airtm": {
      "paymentUrl": "https://app.airtm.com/payment/abc123",
      "expiresAt": "2026-02-25T13:00:00.000Z"
    },
    "created_at": "2026-02-25T12:00:00.000Z"
  }
}

Step 2: User Completes Payment

Redirect the user to the paymentUrl where they:

1. Log into AirTM (or create an account)
2. Choose payment method (bank, mobile money, crypto, etc.)
3. Complete the payment

Step 3: Provider Confirmation (Inbound Webhook)

AirTM notifies your Orchestrator's inbound webhook receiver (POST /api/v1/webhooks/airtm) when payment completes. This is a provider-to-Orchestrator callback — you don't register anything, and your app isn't called.

The Orchestrator then:

1. Verifies the AirTM webhook signature (Svix headers + AIRTM_WEBHOOK_SECRET)
2. Credits the user's balance
3. Emits balance.credited on the SSE stream, which your app can listen to

Using the SDK

Crypto Deposits

import { OfferHubSDK } from '@offerhub/sdk';

const sdk = new OfferHubSDK({
  apiUrl: 'http://localhost:4000',
  apiKey: 'ohk_live_your_api_key'
});

// Get deposit address
const deposit = await sdk.wallet.getDepositAddress('usr_abc123');

// Display to user
console.log(`Send USDC to: ${deposit.address}`);
console.log(`Network: ${deposit.network}`);

// Listen for deposit
sdk.events.on('balance.credited', (event) => {
  if (event.userId === 'usr_abc123') {
    console.log(`Deposit received: ${event.amount}`);
    // Update UI, notify user
  }
});

AirTM Top-ups

// Create top-up request
const topup = await sdk.topups.create({
  userId: 'usr_abc123',
  amount: '100.00',
  currency: 'USD'
});

// Redirect user to payment page
window.location.href = topup.airtm.paymentUrl;

// Or display in iframe/modal
// <iframe src={topup.airtm.paymentUrl} />

// Listen for completion
sdk.events.on('topup.succeeded', (event) => {
  if (event.topupId === topup.id) {
    console.log('Payment received!');
    // Update UI
  }
});

Listening for Deposits

SSE Events

Connect to the event stream:

const events = new EventSource(
  'http://localhost:4000/api/v1/events',
  { headers: { Authorization: 'Bearer ohk_live_...' } }
);

events.onmessage = (e) => {
  const event = JSON.parse(e.data);

  if (event.eventType === 'balance.credited') {
    console.log(`${event.payload.userId} received ${event.payload.amount}`);
    // Update balance display
    updateBalance(event.payload.userId, event.payload.newBalance);
  }
};

Checking Balance

After a deposit, verify the updated balance:

curl http://localhost:4000/api/v1/users/usr_abc123/balance \
  -H "Authorization: Bearer ohk_live_your_api_key"

Response:

{
  "data": {
    "userId": "usr_abc123",
    "available": "100.00",
    "reserved": "0.00",
    "currency": "USD"
  }
}

Minimum Deposits

Supported Assets

Crypto Mode

Currently supported:

Future support planned for:

• EURC (Euro stablecoin)
• Native XLM

AirTM Mode

AirTM supports 200+ funding methods including:

• Bank transfers
• Mobile money (M-Pesa, etc.)
• Cards (Visa, Mastercard)
• Local payment methods
• Crypto (converted to USD)

Error Handling

Crypto Deposit Errors

AirTM Errors

Best Practices

For Developers

1. Always display network — Make sure users know testnet vs mainnet
2. Show asset details — Display USDC issuer for verification
3. Real-time updates — Use SSE for instant balance updates
4. Clear instructions — Guide users through deposit flow

For Users

1. Double-check address — Copy-paste, don't type
2. Verify network — Testnet deposits won't show on mainnet
3. Start small — Test with small amount first
4. Keep transaction ID — For support if needed

Testnet Funding

For development, get testnet USDC:

1. Get testnet XLM — Use Stellar Friendbot
2. Get testnet USDC — Use Circle's testnet faucet or contact OFFER-HUB

# Fund testnet account with XLM
curl "https://friendbot.stellar.org?addr=GCV24WNJYX..."

Next Steps

• Wallets Guide — Understanding invisible wallets
• Withdrawals Guide — Moving funds off-platform
• Orders Guide — Creating your first order