---
name: Venly
description: Use when building payment orchestration systems, integrating fiat-to-crypto conversions, managing multi-currency accounts, or implementing cross-border settlement workflows. Agents should reach for this skill when working with the Fundflow API (on-ramp/off-ramp transactions) or Finance API (accounts, wallets, transfers, virtual bank accounts).
metadata:
    mintlify-proj: venly
    version: "1.0"
---

# Venly Finance Skill

## Product Summary

Venly Finance provides two REST APIs for financial infrastructure: **Fundflow API** for multi-rail fiat-to-crypto conversion (on-ramp and off-ramp), and **Finance API** for embedded accounts, wallets, IBANs, and transfers. Both use OAuth2 client credentials authentication. Base URLs: Fundflow staging `https://api-fundflow-staging.venly.io/v1`, production `https://api-fundflow.venly.io/v1`; Finance staging `https://api-staging.venlyfinance.com/v1`, production `https://api.venlyfinance.com/v1`. Token endpoint: `https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token` (staging) or `https://login.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token` (production). Tokens expire after 5 minutes. See [https://docs.venlyfinance.com](https://docs.venlyfinance.com) for full documentation.

## When to Use

Reach for this skill when:

- **Building payment flows**: Creating on-ramp (fiat → crypto) or off-ramp (crypto → fiat) transactions via Fundflow API
- **Managing user accounts**: Onboarding parties, creating accounts, provisioning wallets, issuing virtual IBANs via Finance API
- **Handling transfers**: Moving funds between accounts, sending crypto to external addresses, or initiating SEPA payouts
- **Integrating authentication**: Exchanging OAuth2 credentials for Bearer tokens and managing token refresh
- **Handling errors**: Resolving version conflicts (409), idempotency issues (422), or KYC/KYB verification blocks
- **Querying reference data**: Listing supported currencies, blockchain networks, bank account types, or available currency pairs
- **Implementing webhooks**: Monitoring ramp request status changes or transfer completions

## Quick Reference

### Authentication Flow

| Step | Action | Endpoint |
|------|--------|----------|
| 1 | Exchange credentials | `POST /auth/realms/VenlyFinance/protocol/openid-connect/token` |
| 2 | Get token | Response includes `access_token` (5 min TTL) |
| 3 | Use token | `Authorization: Bearer YOUR_ACCESS_TOKEN` on all requests |
| 4 | Refresh | Request new token before expiry (30-second buffer recommended) |

### Fundflow API — Ramp Request Lifecycle

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

### Finance API — Party KYC Status

```
PENDING → VERIFIED (outbound transfers unlock)
       → MANUAL_REVIEW → VERIFIED or REJECTED
       → REJECTED
```

### Key Endpoints by Task

| Task | Fundflow | Finance |
|------|----------|---------|
| Verify setup | `GET /v1/company` | `GET /v1/parties` |
| Create ramp request | `POST /v1/ramp-requests` | N/A |
| Approve ramp | `POST /v1/ramp-requests/{id}/approve` | N/A |
| Create account | N/A | `POST /v1/accounts` |
| Create wallet | `POST /v1/company-wallets` | `POST /v1/accounts/{id}/wallets` |
| Create IBAN | N/A | `POST /v1/accounts/{id}/virtual-bank-accounts` |
| Send transfer | N/A | `POST /v1/accounts/{id}/transfers/crypto` or `/fiat` |
| List transfers | N/A | `GET /v1/accounts/{id}/transfers` |
| Calculate fee | `POST /v1/fees/calculate` | N/A |

### Supported Currencies

**Fiat:** EUR, USD, GBP (via SEPA, ACH, SWIFT, FPS, CHAPS)  
**Crypto:** USDC, EURC, USDS, ETH, POL  
**Chains:** Ethereum, Polygon, Base, Arbitrum, Sui

### Pagination Parameters

```bash
GET /v1/resource?page=1&size=50&sortOn=createdAt&sortOrder=DESC
```

Response includes `pagination` object with `pageNumber`, `pageSize`, `numberOfElements`, `numberOfPages`, `hasNextPage`, `hasPreviousPage`.

## Decision Guidance

### When to Use Fundflow vs Finance API

| Use Fundflow | Use Finance |
|--------------|-------------|
| Converting fiat ↔ crypto | Managing user accounts and wallets |
| Company-level ramp requests | Individual/org party onboarding |
| Approval workflows for conversions | Issuing virtual bank accounts (IBANs) |
| Calculating conversion fees | Sending transfers between accounts |
| Managing company bank accounts | Handling KYC/KYB verification |

### When to Use Idempotency vs Versioning

| Use `idempotencyKey` | Use `version` |
|---------------------|---------------|
| Creating resources (`POST`) | Updating resources (`PATCH`, `PUT`) |
| Transfers, payment requests, virtual accounts | Ramp request approvals, amount edits |
| Retry protection on network failure | Optimistic locking for concurrent updates |
| Generate fresh UUID per new operation | Fetch latest version on 409 conflict |

### On-Ramp vs Off-Ramp

| On-Ramp | Off-Ramp |
|---------|----------|
| Fiat → Crypto | Crypto → Fiat |
| Company sends fiat to Venly deposit account | Company sends crypto to Venly deposit wallet |
| Crypto received to company wallet | Fiat received to company bank account |
| Use `fiatCurrencyId`, `cryptoCurrencyId`, `companyWalletId` | Use `cryptoCurrencyId`, `fiatCurrencyId`, `companyBankAccountId` |
| Requires `depositBankAccount` in response | Requires `depositWallet` address in response |

## Workflow

### Fundflow: Create and Approve a Ramp Request

1. **Authenticate**: Exchange client credentials for Bearer token
2. **Verify company**: `GET /v1/company` — confirm `kybStatus: VERIFIED`
3. **Check accounts**: Ensure bank accounts and wallets are `VERIFIED` (manual review may take 1–2 days)
4. **Get currency pairs**: `GET /v1/ramp-requests/on-ramp/pairs` or `/off-ramp/pairs`
5. **Calculate fee** (optional): `POST /v1/fees/calculate` with amount and type
6. **Create ramp request**: `POST /v1/ramp-requests` with rampType, amount, currency IDs, and account IDs
7. **Approve request**: `POST /v1/ramp-requests/{id}/approve` with current `version`
8. **Monitor status**: Poll `GET /v1/ramp-requests/{id}` or use webhooks until `SUCCEEDED` or `FAILED`
9. **Handle payment**: For on-ramp, send fiat to `depositBankAccount` with `paymentReference`; for off-ramp, send crypto to `depositWallet` and update transaction hash

### Finance: Onboard a User and Send a Transfer

1. **Authenticate**: Exchange credentials for Bearer token
2. **Create party**: `POST /v1/parties` with partyType (INDIVIDUAL or ORGANISATION), name, address
3. **Create account**: `POST /v1/accounts` with externalId, chain (BASE or AVALANCHE), partyId
4. **Create wallet**: `POST /v1/accounts/{id}/wallets` with chain
5. **Issue IBAN** (optional): `POST /v1/accounts/{id}/virtual-bank-accounts` with inCurrency, targetCryptocurrency
6. **Fund account**: Customer sends SEPA transfer to IBAN with referenceCode, or create payment session
7. **Wait for KYC**: Poll `GET /v1/parties/{id}` until `kycStatus: VERIFIED` (required for outbound transfers)
8. **Send transfer**: `POST /v1/accounts/{id}/transfers/crypto` or `/fiat` with amount, asset, receiver, idempotencyKey
9. **Track status**: Poll `GET /v1/accounts/{id}/transfers/{id}` until `COMPLETED` or `FAILED`

## Common Gotchas

- **Token expiry**: Tokens are valid for only 5 minutes. Implement refresh logic with a 30-second buffer; don't request a new token on every call.
- **Version conflicts (409)**: Always include the current `version` on update requests. On 409, fetch the latest resource and retry with the new version.
- **Idempotency key reuse**: Keys are bound to the exact request body. Changing the amount or recipient and reusing the key returns 422, not the original response. Generate a fresh UUID for each new operation.
- **KYB/KYC blocks**: Fundflow requires company `kybStatus: VERIFIED` before creating ramp requests. Finance requires party `kycStatus: VERIFIED` before outbound transfers. Inbound funding works regardless.
- **Bank account verification**: Bank accounts require manual review (1–2 business days). Wallets auto-verify. Check status before creating ramp requests.
- **Missing payment reference**: On-ramp requests include a `paymentReference` — the customer must include this in the bank transfer message, or settlement falls back to manual reconciliation (24–48h delay).
- **Wallet ownership verification**: Company wallets require proof of ownership. Complete the verification process before using the wallet in ramp requests.
- **Environment mixing**: Never mix staging and production credentials or base URLs. Maintain separate configuration and gate the switch explicitly.
- **Optimistic locking on wrong endpoint**: Fundflow ramp requests use `version` for updates; Finance transfers use `idempotencyKey` for creation. Don't confuse them.
- **Pagination iteration**: Use `hasNextPage` boolean, not computed page counts — the total can shift between requests.
- **Unknown enum values**: New enum values are not breaking changes. Treat unknown values gracefully rather than throwing errors.

## Verification Checklist

Before submitting work:

- [ ] Token refresh logic is implemented (30-second buffer before expiry)
- [ ] All state-changing requests include `idempotencyKey` (Finance) or `version` (Fundflow updates)
- [ ] 409 conflicts are caught and retried with the latest version
- [ ] KYB/KYC status is verified before creating ramp requests or outbound transfers
- [ ] Bank accounts and wallets are confirmed `VERIFIED` before use
- [ ] Payment references are surfaced to users for on-ramp transactions
- [ ] Pagination uses `hasNextPage` boolean, not computed counts
- [ ] Credentials are stored in environment variables, not hardcoded
- [ ] HTTPS is enforced on all requests
- [ ] Error responses are logged without exposing tokens or secrets
- [ ] Staging environment is used for testing before production deployment

## Resources

**Comprehensive navigation:** [https://docs.venlyfinance.com/llms.txt](https://docs.venlyfinance.com/llms.txt)

**Critical pages:**
- [Getting Started with Fundflow](https://docs.venlyfinance.com/guides/payments/getting-started) — End-to-end ramp request integration
- [Finance API Integration Walkthrough](https://docs.venlyfinance.com/guides/finance/integration-walkthrough) — Onboarding parties, accounts, wallets, and transfers
- [Authentication & Endpoints](https://docs.venlyfinance.com/getting-started/authentication) — Token exchange, refresh patterns, environment URLs

---

> For additional documentation and navigation, see: https://docs.venlyfinance.com/llms.txt