> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venlyfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CardGroup cols={2}>
  <Card title="On-Ramp" icon="arrow-up">
    Fiat → Crypto conversion
  </Card>

  <Card title="Off-Ramp" icon="arrow-down">
    Crypto → Fiat conversion
  </Card>
</CardGroup>

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

<Steps>
  <Step title="1. Authentication">
    Obtain OAuth2 access token via Venly Identity Platform
  </Step>

  <Step title="2. Company Setup">
    Verify company KYB status: `GET /v1/company`
  </Step>

  <Step title="3. Add Bank Accounts">
    Create company bank accounts: `POST /v1/company-bank-accounts`

    Status: PENDING → VERIFIED (manual review)
  </Step>

  <Step title="4. Add Crypto Wallets">
    Register company wallets: `POST /v1/company-wallets`

    Status: PENDING → VERIFIED
  </Step>

  <Step title="5. Create Ramp Requests">
    Create on-ramp or off-ramp: `POST /v1/ramp-requests`
  </Step>
</Steps>

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

```bash theme={null}
# 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

```bash theme={null}
GET /v1/company
GET /v1/company/users
POST /v1/company/users/invite
```

### Bank Accounts

```bash theme={null}
GET /v1/company-bank-accounts
POST /v1/company-bank-accounts
GET /v1/company-bank-accounts/{id}
PATCH /v1/company-bank-accounts/{id}
```

### Crypto Wallets

```bash theme={null}
GET /v1/company-wallets
POST /v1/company-wallets
GET /v1/company-wallets/{id}
PATCH /v1/company-wallets/{id}
```

### Ramp Requests

```bash theme={null}
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

```bash theme={null}
GET /v1/ramp-requests/on-ramp/pairs
GET /v1/ramp-requests/off-ramp/pairs
```

### Fees

```bash theme={null}
GET /v1/fees
POST /v1/fees/calculate
```

### Reference Data

```bash theme={null}
GET /v1/fiat-currencies
GET /v1/crypto-currencies
GET /v1/chains
GET /v1/bank-accounts/config
```

## On-Ramp Example

```bash theme={null}
# 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

```bash theme={null}
# 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:

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
# 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

<Warning>
  **Never expose:**

  * OAuth2 access tokens
  * Client secrets
  * Private keys
  * Seed phrases
</Warning>

✅ **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

<CardGroup cols={3}>
  <Card title="Getting Started" icon="rocket" href="/guides/payments/getting-started">
    Complete setup guide
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/Fundflow-API/company/get-company-details">
    Full API documentation
  </Card>

  <Card title="Accounts Guide" icon="building-columns" href="/guides/payments/accounts">
    Bank accounts & wallets
  </Card>

  <Card title="Transactions" icon="arrow-right-arrow-left" href="/guides/payments/transactions">
    Ramp requests guide
  </Card>

  <Card title="Fees" icon="percent" href="/guides/payments/fees">
    Fee structure
  </Card>

  <Card title="Security" icon="shield" href="/guides/payments/security">
    Security best practices
  </Card>
</CardGroup>

## Support

**Need help?** [Contact us](https://venlyfinance.com/contact)