Getting started

This is the shortest path to a working Finance API integration. You’ll create a party, open an account linked to it, get the party verified, and then issue a virtual bank account.

Base URL (staging): https://api-staging.venlyfinance.com/v1 · Auth: OAuth2 Bearer token — see Authentication. Whether your company is Venly-managed or self-custody changes one step below — see Venly-managed vs self-custody.

Step 1 — Create a party

A party is the person or organisation behind an account. Its status is ACTIVE immediately, but it still starts unverified — verification is a separate step covered below.

curl -X POST https://api-staging.venlyfinance.com/v1/parties \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "partyType": "INDIVIDUAL",
    "externalId": "user-12345",
    "firstName": "Jane",
    "lastName": "Doe"
  }'

Response (201)

{
  "success": true,
  "result": {
    "id": "7e3b9c2a-1f4d-4a8b-9c11-2d6e8f0a1b22",
    "externalId": "user-12345",
    "partyType": "INDIVIDUAL",
    "status": "ACTIVE",
    "firstName": "Jane",
    "lastName": "Doe",
    "createdAt": "2026-01-15T09:30:00Z",
    "updatedAt": "2026-01-15T09:30:00Z",
    "version": 0
  }
}

Save the returned id — it’s the partyId you link in the next step. For an organisation, send partyType: ORGANISATION with name (and optional vatNumber) instead of firstName/lastName.

Step 2 — Open an account linked to the party

An account holds the wallet, IBANs, and transfer history. Pass the partyId from Step 1 to link the party as ACCOUNT_HOLDER. The wallet is provisioned automatically. The only difference between company types is the wallet address:

Venly-managed — Venly creates and holds the wallet. Don’t send an address.
Self-custody — the customer controls the wallet. You must send their address.

curl -X POST https://api-staging.venlyfinance.com/v1/accounts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "acct-12345",
    "name": "Jane Doe — Main",
    "chain": "BASE",
    "partyId": "7e3b9c2a-1f4d-4a8b-9c11-2d6e8f0a1b22"
  }'

curl -X POST https://api-staging.venlyfinance.com/v1/accounts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "acct-12345",
    "name": "Jane Doe — Main",
    "chain": "BASE",
    "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "partyId": "7e3b9c2a-1f4d-4a8b-9c11-2d6e8f0a1b22"
  }'

Response (201)

{
  "success": true,
  "result": {
    "id": "b2a1f0e9-8c7d-4e3a-9f21-0a1b2c3d4e5f",
    "externalId": "acct-12345",
    "name": "Jane Doe — Main",
    "kycStatus": "VERIFICATION_PENDING",
    "status": "ACTIVE",
    "createdAt": "2026-01-15T09:30:00Z",
    "version": 0
  }
}

The account is created with kycStatus: VERIFICATION_PENDING. It exists and can be set up, but it can’t move money yet.

Self-custody omitting address returns 400 "Address is required for SELF_CUSTODY wallet type". See Venly-managed vs self-custody for the full difference (including permits).

Step 3 — Get the party verified

Mint a hosted verification link and hand it to the end-user:

curl -X POST https://api-staging.venlyfinance.com/v1/parties/{partyId}/verification \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The response carries a verificationUrl for the KYC flow (individuals) or KYB flow (organisations). The verdict arrives asynchronously and flips the account’s kycStatus to VERIFIED. If you already verified this user in your own Sumsub account, you can instead forward a share token as party.sumsubToken at account creation. See Onboarding & Verification for both routes. Poll the account until it flips (or better, register a webhook):

curl https://api-staging.venlyfinance.com/v1/accounts/b2a1f0e9-8c7d-4e3a-9f21-0a1b2c3d4e5f \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response (200)

{
  "success": true,
  "result": { "id": "b2a1f0e9-8c7d-4e3a-9f21-0a1b2c3d4e5f", "kycStatus": "VERIFIED", "status": "ACTIVE", "version": 1 }
}

Until kycStatus is VERIFIED, creating virtual bank accounts, transfers, and pay-in sessions all fail with a KYC error — the exact code and HTTP status depend on the operation (e.g. 400 kyc-not-verified for virtual bank accounts, 422 kyc-required for pay-in sessions). See Account verification.

Step 4 — Create a virtual bank account

With the account verified, issue a EUR IBAN so it can be funded via SEPA. Incoming euros are converted to the targetCryptocurrency and credited to the wallet.

curl -X POST https://api-staging.venlyfinance.com/v1/accounts/b2a1f0e9-8c7d-4e3a-9f21-0a1b2c3d4e5f/virtual-bank-accounts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe — EUR",
    "inCurrency": "EUR",
    "targetCryptocurrency": "USDC",
    "idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'

Response (201)

{
  "success": true,
  "result": {
    "id": "4d5e6f70-8192-4a3b-9c4d-5e6f7081920a",
    "accountId": "b2a1f0e9-8c7d-4e3a-9f21-0a1b2c3d4e5f",
    "bankAccountType": "EUR_SEPA",
    "status": "ACTIVE",
    "currency": "EUR",
    "targetCryptocurrency": "USDC",
    "iban": "DE89370400440532013000",
    "bic": "DEUTDEDB",
    "referenceCode": "VFY-7K2Q-931"
  }
}

Give the iban and referenceCode to your customer — the referenceCode is what links their incoming SEPA payment to this account.

Next steps

Full Integration Walkthrough

Funding, transfers, and tracking — end to end.

Self-custody: approving transfers

Sign a permit so a self-custody account can move funds.

Account verification

States, gating, and what works before verification.

API reference

Every endpoint, field, and example.

Overview

Recipes

Onboarding & Verification

Core Concepts

Parties

Accounts

Virtual Bank Accounts

Supported Assets

Wallets

Transfers

Fiat to Crypto Payment Sessions

Payout Bank Accounts

Payout Routes

Payouts

Permits

Allowances

Webhooks

Reference

Step 1 — Create a party

Step 2 — Open an account linked to the party

Step 3 — Get the party verified

Step 4 — Create a virtual bank account

Next steps

Full Integration Walkthrough

Self-custody: approving transfers

Account verification

API reference

​Step 1 — Create a party

​Step 2 — Open an account linked to the party

​Step 3 — Get the party verified

​Step 4 — Create a virtual bank account

​Next steps

Full Integration Walkthrough

Self-custody: approving transfers

Account verification

API reference

Step 1 — Create a party

Step 2 — Open an account linked to the party

Step 3 — Get the party verified

Step 4 — Create a virtual bank account

Next steps