API Overview & Resources

​

API Architecture

https://api-fundflow.venly.io

​

Core Resources

​

Company

• GET /v1/company - Get company details
• GET /v1/company/users - List company users
• POST /v1/company/users/invite - Invite new user
• PUT /v1/company/users/{userId}/role - Update user role
• PATCH /v1/company/users/{userId}/status - Enable/disable user
• DELETE /v1/company/users/{userId} - Remove user

• kybStatus: PENDING, VERIFIED, DENIED
• invoicesUrl: Link to billing portal

​

Bank Accounts

• GET /v1/company-bank-accounts - List all bank accounts
• POST /v1/company-bank-accounts - Create new bank account
• GET /v1/company-bank-accounts/{id} - Get specific account
• PATCH /v1/company-bank-accounts/{id} - Update account name

• EUR_SEPA
• USD_WIRE, USD_ACH, USD_SWIFT
• GBP_FPS, GBP_CHAPS
• OTHER_SWIFT

PENDING → VERIFIED (manual review)
        ↓
      DENIED

• verificationStatus: PENDING, VERIFIED, DENIED
• supportedRampTypes: ON_RAMP, OFF_RAMP, ON_AND_OFF_RAMP

​

Crypto Wallets

• GET /v1/company-wallets - List all wallets
• POST /v1/company-wallets - Register new wallet
• GET /v1/company-wallets/{id} - Get specific wallet
• PATCH /v1/company-wallets/{id} - Update wallet description

• ETHEREUM
• POLYGON
• BASE
• ARBITRUM
• SUI

PENDING → VERIFIED (ownership verification)
        ↓
      DENIED

• verificationStatus: PENDING, VERIFIED, DENIED
• chain: Blockchain network
• address: Wallet address

​

Ramp Requests

• GET /v1/ramp-requests - List all ramp requests
• POST /v1/ramp-requests - Create new ramp request
• GET /v1/ramp-requests/{id} - Get specific request
• POST /v1/ramp-requests/{id}/approve - Approve request
• POST /v1/ramp-requests/{id}/reject - Reject request
• POST /v1/ramp-requests/{id}/cancel - Cancel request
• PUT /v1/ramp-requests/{id}/amount - Edit amount
• PATCH /v1/ramp-requests/{id}/tx-hash - Add transaction hash
• GET /v1/ramp-requests/export - Export all requests

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

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

• rampType: ON_RAMP, OFF_RAMP
• status: Request status
• fromDate, toDate: Date range
• paymentReference: Unique payment reference

​

Fees

• GET /v1/fees - Get company fee configuration
• POST /v1/fees/calculate - Calculate fee for amount

• Company-specific tiers
• Volume-based pricing
• Separate rates for ON_RAMP and OFF_RAMP

​

Currencies

• GET /v1/fiat-currencies - List all fiat currencies
• GET /v1/fiat-currencies/{id} - Get specific currency

• GET /v1/crypto-currencies - List all cryptocurrencies
• GET /v1/crypto-currencies/{id} - Get specific cryptocurrency

• GET /v1/chains - Get supported blockchain networks

​

Deposit Accounts

• GET /v1/deposit-wallets - List deposit wallets (for off-ramp)

• chain: Filter by blockchain network

​

Configuration

• GET /v1/bank-accounts/config - Get bank account configuration
• GET /v1/auth/user - Get authenticated user details

​

Common Patterns

​

Pagination

GET /v1/ramp-requests?page=1&size=50&sortOn=createdAt&sortOrder=DESC

• page: Page number (1-based, default: 1)
• size: Items per page (default: 100, max varies)
• sortOn: Field to sort by
• sortOrder: ASC or DESC

​

Filtering

# Filter ramp requests
GET /v1/ramp-requests?rampType=ON_RAMP&status=AWAITING_APPROVAL

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

# Filter by date range
GET /v1/ramp-requests?fromDate=2024-01-01&toDate=2024-12-31

​

Optimistic Locking

{
  "version": 1,
  // ... other fields
}

1. Fetch the latest version: GET /resource/{id}
2. Update your data with the new version
3. Retry the operation

​

Status Codes

​

Rate Limiting

​

Data Types

​

Common Fields

• id: UUID format (e.g., 123e4567-e89b-12d3-a456-426614174000)

• createdAt, updatedAt, verifiedAt: ISO 8601 format (e.g., 2024-01-15T10:30:00Z)

• Decimal numbers with up to 8 decimal places
• Minimum: 0.00000001

• Integer for optimistic locking
• Increments with each update

​

Best Practices

​

Security

• Store credentials securely (environment variables, vaults)
• Use HTTPS for all requests
• Implement token refresh logic
• Validate all input data
• Log API interactions for audit

• Expose credentials in client-side code
• Store tokens in version control
• Share access tokens between environments
• Ignore error responses

​

Performance

• Use pagination for large datasets
• Cache reference data
• Implement connection pooling
• Use webhooks for real-time updates
• Batch operations when possible

• Poll frequently for status updates
• Fetch all data without pagination
• Make unnecessary API calls
• Ignore rate limits

​

Error Handling

• Handle all HTTP status codes
• Implement retry logic with backoff
• Log errors for debugging
• Provide meaningful error messages to users
• Handle version conflicts gracefully

• Ignore error responses
• Retry indefinitely
• Expose technical errors to end users
• Skip validation

​

Quick Reference

​

Support

• Email: support@venly.io
• Documentation: docs.venly.io
• API Status: Monitor system status for any issues