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

# Getting Started with Fundflow

> End-to-end guide to integrate Fundflow — authentication, creating ramp requests, settlement, and going live with the on-ramp/off-ramp API.

## What is Fundflow?

Fundflow is Venly's enterprise API platform that enables businesses to seamlessly convert between traditional fiat currency and cryptocurrency through a comprehensive REST API.

<CardGroup cols={2}>
  <Card title="On-Ramp" icon="arrow-up">
    Convert fiat to cryptocurrency via API
  </Card>

  <Card title="Off-Ramp" icon="arrow-down">
    Convert cryptocurrency to fiat via API
  </Card>
</CardGroup>

## Key Features

### 🔒 Enterprise-Grade Security

* OAuth2 authentication
* KYB (Know Your Business) verification
* Optimistic locking for concurrent updates
* Wallet ownership verification
* Role-based access control

### 💰 Transparent Pricing

* Company-specific fee tiers
* Volume-based discounts
* Real-time fee calculation API
* Clear exchange rates

### 🌍 Multi-Currency Support

**Fiat Currencies:** EUR, USD, GBP

**Payment Networks:**

* EUR\_SEPA (European SEPA transfers)
* USD\_WIRE, USD\_ACH, USD\_SWIFT (US transfers)
* GBP\_FPS, GBP\_CHAPS (UK transfers)
* OTHER\_SWIFT (International transfers)

**Cryptocurrencies:**

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

**Blockchain Networks:**

* Ethereum
* Polygon
* Base
* Arbitrum
* Sui

***

## Prerequisites

Before you begin, ensure you have:

✅ **Company Account**: [Contact Venly](https://venlyfinance.com/contact) to set up your company account\
✅ **OAuth2 Credentials**: Client ID and secret for authentication\
✅ **API Access**: Staging: `https://api-fundflow-staging.venly.io/v1` · Production: `https://api-fundflow.venly.io/v1`\
✅ **Development Environment**: REST API client or SDK

***

## Integration Steps

```mermaid theme={null}
flowchart TD
    A[Company onboarded] --> B[POST /company-bank-accounts]
    B --> C{Bank account VERIFIED?}
    C -- No --> C
    C -- Yes --> D[POST /company-wallets]
    D --> E{Wallet VERIFIED?}
    E -- No --> E
    E -- Yes --> F{Direction?}
    F -- On-ramp --> G[POST /ramp-requests rampType=ON_RAMP]
    F -- Off-ramp --> H[POST /ramp-requests rampType=OFF_RAMP]
    G --> I[Approve → AWAITING_FUNDS]
    H --> I
    I --> J[Transaction lifecycle<br/>see transactions guide]
```

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

    ```bash theme={null}
    POST https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token

    Content-Type: application/x-www-form-urlencoded

    grant_type=client_credentials
    &client_id=YOUR_CLIENT_ID
    &client_secret=YOUR_CLIENT_SECRET
    ```

    Use the access token in all API requests:

    ```bash theme={null}
    Authorization: Bearer YOUR_ACCESS_TOKEN
    ```
  </Step>

  <Step title="2. Verify Company Status">
    Check your company's KYB verification status

    ```bash theme={null}
    GET /v1/company
    ```

    **Response:**

    ```json theme={null}
    {
      "success": true,
      "result": {
        "id": "company-id",
        "name": "Your Company",
        "kybStatus": "VERIFIED",
        "invoicesUrl": "https://portal.venly.io/invoices"
      }
    }
    ```

    <Note>
      Your company must have `kybStatus: "VERIFIED"` to create ramp requests.
    </Note>
  </Step>

  <Step title="3. Add Bank Accounts">
    Register company bank accounts for fiat transactions

    ```bash theme={null}
    POST /v1/company-bank-accounts
    Content-Type: application/json

    {
      "bankAccountType": "EUR_SEPA",
      "name": "Primary EUR Account",
      "bankName": "Deutsche Bank",
      "companyName": "Your Company Ltd",
      "iban": "DE89370400440532013000",
      "bic": "COBADEFFXXX",
      "bankCountry": "DE",
      "beneficiaryAddressLine1": "123 Main Street",
      "beneficiaryCity": "Berlin",
      "beneficiaryPostalCode": "10115",
      "beneficiaryCountry": "DE",
      "supportedRampType": "ON_AND_OFF_RAMP"
    }
    ```

    **Status Flow:** PENDING → VERIFIED (manual review by Venly)

    <Warning>
      Bank accounts require manual verification. This process may take 1-2 business days.
    </Warning>
  </Step>

  <Step title="4. Add Crypto Wallets">
    Register company cryptocurrency wallets

    ```bash theme={null}
    POST /v1/company-wallets
    Content-Type: application/json

    {
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "chain": "ETHEREUM",
      "description": "Main treasury wallet"
    }
    ```

    **Status Flow:** PENDING → VERIFIED

    Complete the verification process to prove wallet ownership.
  </Step>

  <Step title="5. Get Available Currency Pairs">
    Retrieve supported currency pairs for your operations

    **For On-Ramp:**

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

    **For Off-Ramp:**

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

    **Response:**

    ```json theme={null}
    {
      "success": true,
      "result": [
        {
          "from": {
            "id": "eur-id",
            "currency": "EUR",
            "label": "Euro"
          },
          "to": {
            "id": "usdc-id",
            "currency": "USDC",
            "chain": "ETHEREUM",
            "label": "USD Coin"
          }
        }
      ]
    }
    ```
  </Step>

  <Step title="6. Calculate Fees">
    Calculate fees before creating ramp requests

    ```bash theme={null}
    POST /v1/fees/calculate
    Content-Type: application/json

    {
      "amount": 1000.00,
      "type": "ON_RAMP"
    }
    ```

    **Response:**

    ```json theme={null}
    {
      "success": true,
      "result": {
        "amount": 10.00,
        "percentage": 1.0
      }
    }
    ```
  </Step>

  <Step title="7. Create Ramp Requests">
    Create on-ramp or off-ramp transactions

    **On-Ramp Example:**

    ```bash theme={null}
    POST /v1/ramp-requests
    Content-Type: application/json

    {
      "rampType": "ON_RAMP",
      "amount": 1000.00,
      "fiatCurrencyId": "eur-currency-id",
      "cryptoCurrencyId": "usdc-ethereum-id",
      "companyWalletId": "your-wallet-id"
    }
    ```

    **Off-Ramp Example:**

    ```bash theme={null}
    POST /v1/ramp-requests
    Content-Type: application/json

    {
      "rampType": "OFF_RAMP",
      "amount": 0.5,
      "cryptoCurrencyId": "usdc-ethereum-id",
      "fiatCurrencyId": "eur-currency-id",
      "companyBankAccountId": "your-bank-account-id"
    }
    ```

    Request is created in **AWAITING\_APPROVAL** status.
  </Step>

  <Step title="8. Approve Ramp Request">
    Approve the ramp request to proceed

    ```bash theme={null}
    POST /v1/ramp-requests/{id}/approve
    Content-Type: application/json

    {
      "version": 1
    }
    ```

    Status changes to **AWAITING\_FUNDS**.

    * **On-Ramp**: Customer sends fiat to provided deposit bank account
    * **Off-Ramp**: Customer sends crypto to provided deposit wallet
  </Step>

  <Step title="9. Monitor Status">
    Poll or use webhooks to monitor ramp request status

    ```bash theme={null}
    GET /v1/ramp-requests/{id}
    ```

    **Status Flow:**

    ```
    AWAITING_APPROVAL → AWAITING_FUNDS → PROCESSING → SUCCEEDED
    ```
  </Step>
</Steps>

***

## User Management

### Invite Users

```bash theme={null}
POST /v1/company/users/invite
Content-Type: application/json

{
  "email": "user@example.com",
  "role": "COMPANY_MANAGER",
  "firstName": "John",
  "lastName": "Doe"
}
```

### User Roles

| Role                 | Permissions                           |
| -------------------- | ------------------------------------- |
| **COMPANY\_ADMIN**   | Full access including user management |
| **COMPANY\_MANAGER** | Create and manage ramp requests       |
| **COMPANY\_VIEWER**  | Read-only access                      |

### Update User Role

```bash theme={null}
PUT /v1/company/users/{userId}/role
Content-Type: application/json

{
  "role": "COMPANY_ADMIN"
}
```

***

## Best Practices

### Authentication

<Tip>
  **Token Management**: Implement token refresh logic to handle expired tokens gracefully.
</Tip>

```javascript theme={null}
// Example: Token refresh logic
async function getAccessToken() {
  if (tokenExpired()) {
    return await refreshToken();
  }
  return currentToken;
}
```

### Error Handling

<Tip>
  **Optimistic Locking**: Always handle HTTP 409 conflicts by fetching the latest version and retrying.
</Tip>

```javascript theme={null}
async function updateResource(id, data) {
  try {
    return await api.patch(`/resource/${id}`, data);
  } catch (error) {
    if (error.status === 409) {
      // Fetch latest version and retry
      const latest = await api.get(`/resource/${id}`);
      data.version = latest.version;
      return await api.patch(`/resource/${id}`, data);
    }
    throw error;
  }
}
```

### Pagination

<Tip>
  **Efficient Pagination**: Use appropriate page sizes and implement cursor-based pagination for large datasets.
</Tip>

```bash theme={null}
GET /v1/ramp-requests?page=1&size=50&sortOn=createdAt&sortOrder=DESC
```

### Webhooks

<Tip>
  **Real-time Updates**: Configure webhooks for real-time notifications instead of polling.
</Tip>

Configure webhooks to receive notifications for:

* Ramp request status changes
* Payment received confirmations
* Transaction completions

***

## Testing

### Staging Environment

Use the staging environment for testing:

* Test OAuth2 authentication
* Create test ramp requests
* Verify webhook integrations
* Test error scenarios

### Test Scenarios

1. **Successful On-Ramp**: Create, approve, and complete an on-ramp request
2. **Successful Off-Ramp**: Create, approve, and complete an off-ramp request
3. **Cancellation**: Create and cancel a ramp request
4. **Rejection**: Create and reject a ramp request
5. **Version Conflict**: Test optimistic locking behavior

***

## Common Integration Patterns

### Pattern 1: Automated On-Ramp

```javascript theme={null}
// 1. Create ramp request
const request = await createRampRequest({
  rampType: 'ON_RAMP',
  amount: 1000,
  fiatCurrencyId: eurId,
  cryptoCurrencyId: usdcId,
  companyWalletId: walletId
});

// 2. Auto-approve if within limits
if (request.amount <= autoApprovalLimit) {
  await approveRampRequest(request.id, request.version);
}

// 3. Monitor status via webhook
// Webhook handler will process status updates
```

### Pattern 2: Batch Processing

```javascript theme={null}
// Process multiple ramp requests efficiently
const requests = await listRampRequests({
  status: 'AWAITING_APPROVAL',
  page: 1,
  size: 100
});

for (const request of requests.result) {
  if (shouldApprove(request)) {
    await approveRampRequest(request.id, request.version);
  }
}
```

***

## Security Considerations

<Warning>
  **Never expose:**

  * OAuth2 client secrets
  * Access tokens in client-side code
  * Private keys or seed phrases
  * API credentials in version control
</Warning>

### Secure Storage

* Store credentials in environment variables or secure vaults
* Use HTTPS for all API communications
* Implement proper access controls
* Rotate credentials regularly

### API Scopes

Request only the OAuth2 scopes you need:

* `view:ramp-request` - View ramp requests
* `create:ramp-request` - Create ramp requests
* `approve:ramp-request` - Approve ramp requests
* `manage:company-wallet` - Manage wallets
* `manage:company-bank-account` - Manage bank accounts

***

## Next Steps

<CardGroup cols={3}>
  <Card title="API Reference" icon="code" href="/api-reference/Fundflow-API/company/get-company-details">
    Explore full API documentation
  </Card>

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

  <Card title="Transactions" icon="arrow-right-arrow-left" href="/guides/payments/transactions">
    Create and manage ramp requests
  </Card>

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

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

  <Card title="Quick Reference" icon="book" href="/guides/payments/quick-reference">
    Quick API overview
  </Card>

  <Card title="Multi-Rail Routing" icon="shuffle" href="/guides/multi-rail-routing/introduction">
    Understand how payments are automatically routed across rails
  </Card>
</CardGroup>

***

## Support

Need help with integration?

* **Contact**: [venlyfinance.com/contact](https://venlyfinance.com/contact)
* **API Status**: Check system status for any ongoing issues