Quick Reference Guide - Venly Finance

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. Authentication

Obtain OAuth2 access token via Venly Identity Platform

2. Company Setup

Verify company KYB status: GET /v1/company

3. Add Bank Accounts

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

4. Add Crypto Wallets

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

Type	Region	Required Fields
EUR_SEPA	Europe	IBAN, BIC
USD_WIRE	US	Account #, Routing #
USD_ACH	US	Account #, Routing #
USD_SWIFT	US	BIC, Account #, Bank address
GBP_FPS	UK	Account #, Sort code
GBP_CHAPS	UK	Account #, Sort code
OTHER_SWIFT	International	Currency, BIC, IBAN/Account #

Common API Endpoints

Authentication

# Staging token endpoint
POST https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token
# Production token endpoint
POST https://login.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token

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}/tx-hash
{
  "blockchainTransactionHash": "0x...",
  "version": 2
}

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

User Roles

Role	Permissions
COMPANY_ADMIN	Full access + user management
COMPANY_MANAGER	Create/manage ramp requests
COMPANY_VIEWER	Read-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

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Version Conflict
500	Server 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

Quick Links

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 us

​Platform Overview

​Key Concepts

On-Ramp

Off-Ramp

​Supported Currencies

​Fiat Currencies

​Cryptocurrencies

​Blockchain Networks

​Quick Start Flow

​Ramp Request Lifecycle

​Bank Account Types

​Common API Endpoints

​Authentication

​Company & Users

​Bank Accounts

​Crypto Wallets

​Ramp Requests

​Currency Pairs

​Fees

​Reference Data

​On-Ramp Example

​Off-Ramp Example

​User Roles

​Optimistic Locking

​Status Codes

​Pagination

​Filtering

​Security Best Practices

​Common Issues

​Rate Limits

​Webhooks

​Quick Links

Getting Started

API Reference

Accounts Guide

Transactions

Fees

Security

​Support

Platform Overview

Key Concepts

Supported Currencies

Fiat Currencies

Cryptocurrencies

Blockchain Networks

Quick Start Flow

Ramp Request Lifecycle

Bank Account Types

Common API Endpoints

Authentication

Company & Users

Bank Accounts

Crypto Wallets

Ramp Requests

Currency Pairs

Fees

Reference Data

On-Ramp Example

Off-Ramp Example

User Roles

Optimistic Locking

Status Codes

Pagination

Filtering

Security Best Practices

Common Issues

Rate Limits

Webhooks

Quick Links

Support