At a Glance
- Client: A United States-based fintech company building digital asset infrastructure
- Challenge: Integrate multiple fiat-to-crypto providers (OwlPay, Yellow Card, MoneyGram, Brale) behind one connector layer, with USDC bridging to Hedera — in two weeks
- Timeline: Production-ready platform delivered in 2 weeks of intensive development
- Solution: Scalable connector architecture with partner adapters, smart routing, multi-leg transaction orchestration, and Hedera HTS bridge
- Outcome: Fully functional on-ramp, off-ramp, and cross-chain bridge covering 30+ countries and 7+ blockchains, with plug-and-play documentation for adding future partners
Live Demo: cryptoramp.agilecreativeminds.nl Username: demo / Password: demo123 If the password is no longer working, please request a new one via the request a password for the demo.
The Client
A United States-based fintech company that specializes in digital asset infrastructure. They needed to offer fiat-to-crypto on-ramp and off-ramp capabilities to their customers across multiple regions — the US, Africa, Europe, and emerging markets — each with different banking systems, currencies, and regulatory landscapes.
They had already identified their preferred payment partners but had no unified platform to connect them. Each partner had its own API, authentication model, and transaction lifecycle. The client needed a single connector layer that would abstract these differences away and make it easy to add new partners as the business grew.
The Challenge
The scope was demanding and the timeline was tight:
- Four partners, four completely different APIs. OwlPay uses API keys with idempotency headers. Yellow Card requires HMAC-SHA256 signatures on every request. Brale uses OAuth2 client credentials. MoneyGram uses Stellar's SEP-10/SEP-24 interactive protocol. All four needed to sit behind one standardized interface.
- On-ramp and off-ramp through every partner. Users needed to purchase USDC with fiat currency (on-ramp) and convert USDC back to fiat (off-ramp) through any available partner — with real-time quote comparison, transaction initiation, status tracking, and webhook processing.
- Cross-chain bridging to Hedera. Most partners deliver USDC on Ethereum or Polygon. The client's ecosystem runs on Hedera. USDC purchased on an EVM chain needed to be automatically bridged to Hedera's Token Service (HTS) — and reverse bridging back to EVM chains for off-ramp had to work too.
- Multi-leg transaction orchestration. A single user action like "buy USDC on Hedera" actually requires two operations: purchase USDC on Ethereum via a partner, then bridge it to Hedera via Hashport. These legs needed to execute in sequence, with each step tracked independently and the entire flow completing automatically.
- Production-grade from day one. Double-entry ledger for every money movement. Full audit trail on every state transition. Idempotent operations to prevent duplicate charges. Comprehensive error classification (transient vs hard vs rate-limit) for intelligent retry logic.
- Two-week delivery. The client had commitments to their own customers. Daily progress updates and feature demos were expected throughout development.
Our Solution
We designed and built a connector platform around three core architectural decisions:
1. Partner Adapters with Capability-Based Routing
Every payment partner implements a standardized adapter interface. The adapter handles all partner-specific concerns — authentication, request formatting, response normalization, webhook parsing — and exposes a clean, uniform API to the rest of the system.
Each adapter also declares structured capabilities: which regions it supports, which currencies, which blockchains, supported assets, amount limits, priority, and estimated fee percentage.
The route planner uses these capabilities to automatically select the best partner for any given request. A Nigerian user paying in NGN is routed to Yellow Card. A US user buying USDC on Ethereum is routed to OwlPay or Brale based on fee and priority. No hardcoded routing rules — the system evaluates capabilities at request time.
The four partners we integrated:
- OwlPay — US market, USD, 7 blockchains (Ethereum, Polygon, Stellar, Avalanche, Solana, Optimism, Arbitrum)
- Yellow Card — 20+ African countries, 13 currencies, mobile money and bank transfer support
- Brale — US market, USD, 9+ blockchains including emerging L2s
- MoneyGram — 170+ countries via cash at physical locations, Stellar-native USDC
Adding a fifth partner means implementing one adapter file. No changes to routing, orchestration, the dashboard, or any other part of the system.
2. Multi-Leg Execution Engine
The execution engine drives transactions through their full lifecycle. When a user initiates an on-ramp to Hedera, the system:
- Computes a route plan (on-ramp leg + bridge leg)
- Creates a PaymentIntent with planned legs in the database
- Executes Leg 1 through the selected partner adapter
- Stores the partner's transaction ID, creates ledger entries
- Polls or receives webhooks to advance the leg to completion
- Automatically starts Leg 2 (bridge) when Leg 1 completes
- Advances the bridge through its own lifecycle (lock → bridge → release)
- Marks the PaymentIntent as completed when all legs finish
Each leg has its own state machine (PENDING → EXECUTING → AWAITING_CONFIRMATION → COMPLETED) and can be retried independently if it fails. Every state transition creates an audit event.
3. Hedera Bridge Integration
The bridge module handles cross-chain USDC movement between EVM chains and Hedera:
- EVM → Hedera: USDC is locked on the source chain, minted as an HTS token on Hedera via Hashport
- Hedera → EVM: HTS USDC is burned on Hedera, released on the destination EVM chain
- Direct path: If a partner delivers USDC directly on Hedera (future capability), the bridge step is skipped entirely
The bridge has its own progression (pending → locking → bridging → releasing → completed), visualized in the dashboard so operators can track every step.
Architecture
┌──────────────────────────────────────────────────────────────────┐
│ Next.js Dashboard │
│ Login → On-Ramp / Off-Ramp / Bridge / Transactions │
└──────────────────────┬───────────────────────────────────────────┘
│ REST API (JWT + API Key auth)
▼
┌──────────────────────────────────────────────────────────────────┐
│ Nest.js API (Fastify) │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────────┐ │
│ │ RoutePlanner │→│ ExecutionSvc │→│ Partner Adapters │ │
│ │ │ │ │ │ • OwlPay (US) │ │
│ │ Capability- │ │ Drives legs │ │ • YellowCard (Africa) │ │
│ │ based select│ │ through state│ │ • Brale (US) │ │
│ │ + plan │ │ machine │ │ • MoneyGram (Global) │ │
│ └─────────────┘ └──────────────┘ └─────────────────────────┘ │
│ │ │
│ ┌───────────────┐ ┌────┴────────┐ ┌────────────────────────┐ │
│ │ Webhook Proc. │ │ Bridge Svc │ │ Transaction Svc │ │
│ │ Signature │ │ Hashport SDK│ │ State machine + Ledger │ │
│ │ verify + leg │ │ Hedera HTS │ │ Audit trail │ │
│ │ state advance │ │ │ │ Idempotency │ │
│ └───────────────┘ └─────────────┘ └────────────────────────┘ │
└──────────────────────┬────────────────────────┬──────────────────┘
▼ ▼
┌──────────────┐ ┌──────────────────┐
│ PostgreSQL │ │ Redis │
│ Intents, Legs│ │ BullMQ Queues │
│ Ledger, Audit│ │ Rate Limiting │
│ Multi-tenant │ │ Caching │
└──────────────┘ └──────────────────┘Key architectural decisions:
- Strategy + Adapter pattern — Partner-specific logic is completely isolated. The orchestration layer never touches partner code.
- Multi-tenant from day one — Every table carries a tenant ID. API keys and dashboard users are tenant-scoped. The platform supports multiple clients on a single deployment.
- Async execution — Intent creation returns immediately. The execution engine processes legs asynchronously. Webhooks and status polling both feed into the same state machine.
- Double-entry ledger — Every money movement creates paired debit/credit records for reconciliation.
Technology Stack
- TypeScript with strict mode — branded types for money safety (prevents mixing dollars with cents at compile time)
- Nest.js with Fastify adapter — modular architecture, dependency injection, auto-generated Swagger docs
- Next.js — dashboard with server-side rendering, API path proxying to backend
- PostgreSQL — payment intents, legs, ledger entries, audit logs, webhooks
- Prisma — type-safe ORM with migration management
- Redis + BullMQ — async job processing, rate limiting, caching
- @hashgraph/sdk — direct Hedera HTS operations (account queries, token association, transfers)
- Hashport SDK — cross-chain EVM ↔ Hedera bridging
- Docker Compose — containerized deployment with Traefik reverse proxy and automatic HTTPS
What We Delivered
Connector Layer
- Scalable connector architecture with standardized partner adapter interface
- Four partner integrations (OwlPay, Yellow Card, MoneyGram, Brale) — each with full on-ramp, off-ramp, status tracking, and webhook support
- Capability-based route planner that selects optimal partner per request
- Partner-agnostic request/response normalization
- Connector pattern documentation for adding new partners
On-Ramp & Off-Ramp
- Fiat → USDC conversion through any integrated partner with real-time quote comparison
- USDC → fiat conversion with bank account/payment method support
- Transaction initiation, monitoring, and completion across all partners
- USDC delivery tracking to user wallet upon successful settlement
Hedera Bridge
- Cross-chain bridging for USDC between EVM chains and Hedera HTS
- Reverse bridging support (Hedera → EVM for off-ramp scenarios)
- Multi-step bridge lifecycle with monitoring and confirmation tracking
- Comprehensive testing across bridge scenarios
Dashboard
- Username/password login with JWT sessions (45-minute TTL, no email-based auth)
- On-ramp flow: quote comparison across partners → initiation → live execution tracking
- Off-ramp flow: quote → initiation → completion tracking
- Bridge visualization with step-by-step progression
- Transaction list with drill-down to legs, events, and route plans
- Partner overview with capabilities and health status
Security & Infrastructure
- API key authentication with per-key rate limits and role-based access (Admin, Operator, Read-only, Demo)
- HMAC-SHA256 webhook signature verification per partner
- Input validation on all endpoints
- Audit logging for all transactions and API calls
- Swagger/OpenAPI documentation
- Docker Compose for development and production
- Health check endpoints for monitoring
- Mock mode for demo and development — switch to live partners with a config change
The Results
- 4 payment partners integrated behind one connector layer — each with a fundamentally different API, auth model, and payment flow
- Countries covered across US, Africa, Europe, and emerging markets
- Fiat currencies supported (USD, EUR, GBP, NGN, GHS, KES, ZAR, and more)
- 7+ blockchains for USDC delivery (Ethereum, Polygon, Stellar, Solana, Avalanche, Base, Hedera)
- Multi-leg transactions execute automatically — on-ramp + bridge completes without manual intervention
- Full audit trail — every state change, every money movement, every partner interaction is logged and traceable
- Plug-and-play extensibility — adding a new partner requires implementing one adapter, no changes to routing, orchestration, or the dashboard
- Delivered in 2 weeks with daily progress demos, comprehensive testing, and production deployment
Why It Worked
The client came to us with a complex integration challenge and an aggressive timeline. Four partners. Four different APIs. Cross-chain bridging. Multi-leg orchestration. Two weeks.
The key was treating the problem as an architecture problem first. Before writing any partner-specific code, we designed the connector interface, the capability model, the state machine, and the execution engine. Once that foundation was solid, each partner integration was a matter of implementing one adapter against a well-defined contract.
The other critical decision was building the multi-leg execution engine as a separate concern from intent creation. This meant on-ramp, off-ramp, and bridge operations all flow through the same orchestration pipeline. When the client eventually adds cross-chain off-ramp (Hedera → EVM → fiat), the execution engine already handles it — just add the right legs to the route plan.
About Us
Agile Creative Minds builds custom platforms for companies that need complex integrations delivered fast — without sacrificing security, maintainability, or production readiness.
If your business needs to integrate with payment partners, blockchain networks, or multi-step transactional workflows — we'd love to hear from you.
The work described here formed part of a larger project delivered for a client. Details have been anonymised to protect confidentiality, but the technical implementation, results, and process reflect real work done.