Skip to main content

​
Platform Overview

Venly Fundflow enables businesses to convert between fiat and crypto through a comprehensive API with enterprise-grade security and compliance.

​
Key Concepts

On-Ramp

Fiat → Crypto conversion

Off-Ramp

Crypto → Fiat conversion

​
Supported Currencies

​
Fiat Currencies

EUR, USD, GBP - via multiple payment networks (SEPA, ACH, SWIFT, FPS, CHAPS)

​
Cryptocurrencies

  • USDC (Ethereum)
  • EURC (Ethereum)
  • USDS (Ethereum)
  • ETH (Ethereum)
  • POL (Polygon)

​
Blockchain Networks

Ethereum, Polygon, Base, Arbitrum, Sui

​
Quick Start Flow

1

1. Authentication

Obtain OAuth2 access token via Venly Identity Platform
2

2. Company Setup

Verify company KYB status: GET /v1/company
3

3. Add Bank Accounts

Create company bank accounts: POST /v1/company-bank-accountsStatus: PENDING → VERIFIED (manual review)
4

4. Add Crypto Wallets

Register company wallets: POST /v1/company-walletsStatus: PENDING → VERIFIED
5

5. Create Ramp Requests

Create on-ramp or off-ramp: POST /v1/ramp-requests

​
Ramp Request Lifecycle

AWAITING_APPROVAL → AWAITING_FUNDS → PROCESSING → SUCCEEDED
       ↓                  ↓
   CANCELLED          REJECTED
   REJECTED           DENIED
   DENIED             BLOCKED
   BLOCKED

​
Bank Account Types

TypeRegionRequired Fields
EUR_SEPAEuropeIBAN, BIC
USD_WIREUSAccount #, Routing #
USD_ACHUSAccount #, Routing #
USD_SWIFTUSBIC, Account #, Bank address
GBP_FPSUKAccount #, Sort code
GBP_CHAPSUKAccount #, Sort code
OTHER_SWIFTInternationalCurrency, BIC, IBAN/Account #

​
Common API Endpoints

​
Authentication

GET /v1/auth/user

​
Company & Users

GET /v1/company
GET /v1/company/users
POST /v1/company/users/invite

​
Bank Accounts

GET /v1/company-bank-accounts
POST /v1/company-bank-accounts
GET /v1/company-bank-accounts/{id}
PATCH /v1/company-bank-accounts/{id}

​
Crypto Wallets

GET /v1/company-wallets
POST /v1/company-wallets
GET /v1/company-wallets/{id}
PATCH /v1/company-wallets/{id}

​
Ramp Requests

GET /v1/ramp-requests
POST /v1/ramp-requests
GET /v1/ramp-requests/{id}
POST /v1/ramp-requests/{id}/approve
POST /v1/ramp-requests/{id}/reject
POST /v1/ramp-requests/{id}/cancel
PUT /v1/ramp-requests/{id}/amount
PATCH /v1/ramp-requests/{id}/tx-hash

​
Currency Pairs

GET /v1/ramp-requests/on-ramp/pairs
GET /v1/ramp-requests/off-ramp/pairs

​
Fees

GET /v1/fees
POST /v1/fees/calculate

​
Reference Data

GET /v1/fiat-currencies
GET /v1/crypto-currencies
GET /v1/chains
GET /v1/bank-accounts/config

​
On-Ramp Example

# 1. Get available pairs
GET /v1/ramp-requests/on-ramp/pairs

# 2. Create request
POST /v1/ramp-requests
{
  "rampType": "ON_RAMP",
  "amount": 1000.00,
  "fiatCurrencyId": "eur-id",
  "cryptoCurrencyId": "usdc-id",
  "companyWalletId": "wallet-id"
}

# 3. Approve request
POST /v1/ramp-requests/{id}/approve
{
  "version": 1
}

# 4. Send fiat from company bank account to Venly deposit account
#    (use depositBankAccount details from response + paymentReference)
# 5. System processes and sends crypto to company wallet

​
Off-Ramp Example

# 1. Get available pairs
GET /v1/ramp-requests/off-ramp/pairs

# 2. Create request
POST /v1/ramp-requests
{
  "rampType": "OFF_RAMP",
  "amount": 1000,
  "cryptoCurrencyId": "usdc-id",
  "fiatCurrencyId": "eur-id",
  "companyBankAccountId": "bank-id"
}

# 3. Approve request
POST /v1/ramp-requests/{id}/approve
{
  "version": 1
}

# 4. Send crypto from company wallet to Venly deposit wallet
#    (use depositWallet address from response)
# 5. Add transaction hash
PATCH /v1/ramp-requests/{id}/initiate
{
  "blockchainTransactionHash": "0x...",
  "version": 2
}

# 6. System processes and sends fiat to company bank account

​
User Roles

RolePermissions
COMPANY_ADMINFull access + user management
COMPANY_MANAGERCreate/manage ramp requests
COMPANY_VIEWERRead-only access

​
Optimistic Locking

All update operations require a version field: 
{
  "version": 1,
  // ... other fields
}
Version conflict (HTTP 409)? → Fetch latest version and retry

​
Status Codes

CodeMeaning
200Success
201Created
400Bad Request
401Unauthorized
403Forbidden
404Not Found
409Version Conflict
500Server Error

​
Pagination

GET /v1/ramp-requests?page=1&size=50&sortOn=createdAt&sortOrder=DESC
Response includes:
  • pagination: Page info
  • sort: Sort configuration
  • result: Array of items

​
Filtering

# Filter ramp requests
GET /v1/ramp-requests?rampType=ON_RAMP&status=AWAITING_APPROVAL&fromDate=2024-01-01&toDate=2024-12-31

# Filter wallets
GET /v1/company-wallets?chain=ETHEREUM&verificationStatus=VERIFIED

# Filter bank accounts
GET /v1/company-bank-accounts?verificationStatus=VERIFIED

​
Security Best Practices

Never expose:
  • OAuth2 access tokens
  • Client secrets
  • Private keys
  • Seed phrases
✅ Do:
  • Use OAuth2 with appropriate scopes
  • Implement token refresh
  • Store credentials securely
  • Use HTTPS only
  • Validate webhook signatures

​
Common Issues

Version conflict (409)? → Fetch latest resource and retry with new version Request stuck in AWAITING_FUNDS? → Verify payment was sent with correct reference Wallet verification failed? → Check verification process requirements Cannot create ramp request? → Ensure company KYB is VERIFIED and accounts are VERIFIED

​
Rate Limits

Follow standard API rate limiting practices:
  • Implement exponential backoff
  • Cache reference data
  • Use pagination efficiently

​
Webhooks

Configure webhooks for real-time updates on:
  • Ramp request status changes
  • Payment received notifications
  • Transaction completions

Getting Started

Complete setup guide

API Reference

Full API documentation

Accounts Guide

Bank accounts & wallets

Transactions

Ramp requests guide

Fees

Fee structure

Security

Security best practices

​
Support

Need help? Contact Venly support at support@venly.io