Quick Reference Guide

Cheat sheet for Fundflow — base URLs, auth flow, ramp request lifecycle, and the most-used endpoints on a single page.

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-accounts

   Status: PENDING → VERIFIED (manual review)

4. 4. Add Crypto Wallets

   Register company wallets: POST /v1/company-wallets

   Status: 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

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 Venly support at [e-mail]