Building Real-Time Event-Driven Applications with FluxRail: A Step-by-Step Guide

Introduction

Modern blockchain applications demand real-time responsiveness. Whether you're tracking high-value transfers, automating compliance workflows, or powering a cross-border payout system, waiting for polling intervals is no longer acceptable. FluxRail provides a unified API that turns blockchain events into actionable, signed webhooks. In this guide, you'll build a complete event-driven application using FluxRail Core, Pay, and Payouts—all with simple HTTP calls.

Prerequisites

• A FluxRail account (free tier available at fluxrail.io)
• Your API key: flux_test_... for sandbox testing
• A webhook endpoint (we'll use webhook.site for testing)
• cURL or any HTTP client

Step 1: Create a Webhook Endpoint

First, register a webhook URL where FluxRail will deliver events. Each event includes an HMAC SHA-256 signature in the X-FluxRail-Signature header for verification.

curl -X POST https://api.fluxrail.io/api/v1/webhooks \
  -H "X-API-Key: flux_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-webhook-endpoint.com/hook",
    "description": "My production webhook",
    "events": ["*"]
  }'

Save the returned id and secret (the secret is used to verify signatures).

Step 2: Subscribe to Blockchain Addresses

Monitor any address across 36+ chains. FluxRail will fire events on incoming/outgoing transactions, token transfers, and more.

curl -X POST https://api.fluxrail.io/api/v1/subscriptions \
  -H "X-API-Key: flux_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "network": "ethereum",
    "webhook_id": "wh_abc123",
    "events": ["transaction.confirmed"]
  }'

You can also subscribe in bulk:

curl -X POST https://api.fluxrail.io/api/v1/subscriptions/bulk \
  -H "X-API-Key: flux_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptions": [
      {"address": "0x...", "network": "polygon", "events": ["*"], "webhook_id": "wh_abc123"},
      {"address": "0x...", "network": "arbitrum", "events": ["*"], "webhook_id": "wh_abc123"}
    ]
  }'

Step 3: Process Incoming Events

When a monitored address receives a transaction, FluxRail sends a POST to your webhook with a payload like:

{
  "id": "evt_123",
  "type": "transaction.confirmed",
  "data": {
    "network": "ethereum",
    "transaction_hash": "0xabc...",
    "from": "0x...",
    "to": "0x1234567890abcdef1234567890abcdef12345678",
    "value": "1000000000000000000",
    "asset": "ETH",
    "confirmations": 12
  },
  "created_at": "2025-03-15T10:30:00Z"
}

Always verify the signature using your webhook secret. FluxRail uses HMAC SHA-256 with the raw body and the X-FluxRail-Signature header.

Step 4: Automate Payouts on Event

Now integrate FluxRail Pay and Payouts. For example, when a deposit is detected, automatically trigger a payout to a beneficiary in Nigeria.

First, create a customer:

curl -X POST https://api.fluxrail.io/api/v1/payouts/customers \
  -H "X-API-Key: flux_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user-101",
    "type": "individual",
    "individual": {
      "given_name": "Jane",
      "family_name": "Doe",
      "email": "jane@example.com"
    }
  }'

Initiate KYC (returns a hosted link):

curl -X POST https://api.fluxrail.io/api/v1/payouts/customers/user-101/kyc-link \
  -H "X-API-Key: flux_test_YOUR_API_KEY"

Once KYC is approved, fund the customer's wallet (or use a virtual account). Then send a payout:

curl -X POST https://api.fluxrail.io/api/v1/payouts/customers/user-101/send \
  -H "X-API-Key: flux_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "USDT",
    "network": "TRC20",
    "amount": "50",
    "dest_currency": "NGN",
    "bank_code": "058",
    "bank_account_number": "0123456789"
  }'

FluxRail handles conversion, compliance screening, and settlement via local rails (e.g., NIBSS in Nigeria). The response includes a rail field (e.g., ngn_bank) and a status of pending_approval.

Step 5: Monitor and Retry

Track all events and their delivery status:

curl -X GET https://api.fluxrail.io/api/v1/events \
  -H "X-API-Key: flux_test_YOUR_API_KEY"

Retry a failed event:

curl -X POST https://api.fluxrail.io/api/v1/events/evt_123/retry \
  -H "X-API-Key: flux_test_YOUR_API_KEY"

Step 6: Full Workflow Example

Here's a complete scenario: monitor a USDC deposit address, and on confirmation, convert to USDT and pay out to a Nigerian bank account.

1. Subscribe to the deposit address (Step 2).
2. Webhook receives transaction.confirmed with the deposit amount.
3. Call POST /api/v1/liquidity/quote to get a conversion rate from USDC to USDT.
4. Call POST /api/v1/liquidity/execute/{quote_id} to swap.
5. Call POST /api/v1/payouts/customers/{id}/send with the converted USDT.

All steps are idempotent and trackable via id fields.

Best Practices

• Always verify webhook signatures before processing.
• Use client_reference_id on transfers and payouts for idempotency.
• Handle webhook retries gracefully—FluxRail retries with exponential backoff.
• Monitor webhook delivery logs via GET /api/v1/webhooks/{id}/deliveries.

Conclusion

With FluxRail, you've built a real-time event-driven application that monitors blockchains, executes gas-free transfers, and settles fiat payouts—all through a single API. No SDKs, no complex infrastructure. Start building today at fluxrail.io.