Make your first Venly Finance API call today, on your own machine
Developers
Connect your AI assistant to our docs MCP server, or run your first call in the TypeScript SDK’s mock mode: no signup, no credentials, no network.
Build with your AI assistant
Help me start building on Venly Finance. Use the docs MCP server at https://docs.venlyfinance.com/mcp, or https://docs.venlyfinance.com/llms.txt if you have no MCP. Install @venlyfinance/sdk with environment "mock", which needs no credentials, create an INDIVIDUAL party, then help me build my integration from the documented flow.
The docs MCP server, https://docs.venlyfinance.com/mcp, needs no API key.
Make your first call
Request sandbox credentials
Three environments, one codebase
Mock mode
Today
No signup, no credentials, no network. It runs on your machine.
Sandbox
After a scoping call
Credentials sent to you directly. Sandbox calls move no real funds.
Production
When you go live
Separate production credentials and the scopes your flow needs.
Both APIs sign in the same way: OAuth2 client credentials at one token endpoint.
Accounts for your customers: the Finance API
Conversions of your company’s own funds: Fundflow
Build with AI
Recipes your AI assistant can build from the docs
Each prompt names the documentation page it follows. The build prompts ask for the SDK in mock mode, so the code your assistant writes runs today with no credentials. Paste one into any assistant connected to the docs MCP server.
Onboard a customer and send a first transfer
The integration walkthrough: a party, an account, verification, funding and a transfer, with the statuses between them.
Use the Venly Finance docs MCP server (https://docs.venlyfinance.com/mcp) and follow the integration walkthrough at https://docs.venlyfinance.com/guides/finance/integration-walkthrough. In TypeScript with @venlyfinance/sdk and environment "mock", write a script that creates an INDIVIDUAL party, opens an account for it, approves the verification with venly.mock.advanceVerification, funds the account through a virtual bank account with venly.mock.simulations.inbound.credit, sends a crypto transfer with my own idempotencyKey and settles it with venly.mock.advanceTransfer. Log every status. Take each field name from the API reference.
Give a customer USD or EUR receiving details
Virtual bank accounts: USD by ACH or EUR by SEPA, converted to a stablecoin when the money arrives, with a referenceCode the payer quotes.
Use the Venly Finance docs MCP server (https://docs.venlyfinance.com/mcp) and read https://docs.venlyfinance.com/guides/finance/virtual-bank-accounts. Add an endpoint to my app that creates a virtual bank account for a verified account, with inCurrency USD or EUR and targetCryptocurrency USDC. Save the idempotencyKey before sending, return the deposit details and the referenceCode my customer must quote, and handle a EUR account that comes back PENDING until its IBAN arrives. Build it on @venlyfinance/sdk and test the EUR path in mock mode first.
Handle webhooks and retries safely
Webhooks and idempotency: delivery at least once, no amounts in events, one saved key per money movement.
Use the Venly Finance docs MCP server (https://docs.venlyfinance.com/mcp) and read https://docs.venlyfinance.com/guides/finance/webhooks and https://docs.venlyfinance.com/guides/finance/idempotency. Write a webhook handler for my stack that checks the authentication header I registered, switches on eventType, ignores the types it does not handle, processes each resource id and target status once, and reads amounts back over the API because events carry none. Then show how my transfer code saves an idempotencyKey before sending and retries with the same key.
Issue wallets, receive fiat, pay out fiat
The recipe in the docs: a Wallet API wallet registered as a self-custody Finance account, bank details to receive fiat, and a pay-out the customer funds.
Use the Venly Finance docs MCP server (https://docs.venlyfinance.com/mcp) and follow the recipe at https://docs.venlyfinance.com/guides/finance/recipes/wallet-api-end-to-end. Give me an implementation plan for my stack: every call in order, the status I wait for after each one, and a flag on each step that completes asynchronously. Keep to what the recipe covers and list what it leaves out.
Recipe: issue wallets, receive fiat, pay out fiat
No MCP in your assistant? Give it https://docs.venlyfinance.com/llms-full.txt, the guides and the API reference as one text file, with the same prompt.
What your assistant can read
llms.txt
An index of the documentation, one line per page.
llms-full.txt
The guides and the API reference as one text file.
skill.md
An agent skill for the two APIs: base URLs, authentication, the object model and when to use which API.
Docs MCP server
Add the server to your agent. It can search the documentation and read any page.
Venly Finance MCP, in mock mode
SDK-backed tools for parties, accounts, receiving details and transfers. Its write tools run only against the mock sandbox, with no credentials and no network, and refuse any other base URL.
Add it to your agent’s MCP config
Or add it to Claude Code in one line
Then ask your agent to run the server’s build_international_account prompt.
Tools your agent can call in mock mode
The server lists 35 tools in all; these are the ones for building an account flow. This is what create_party returned in mock mode:
Writes, mock only
Reads
Build your own interface
SDK, React components and MCP tools for your own customer experience.
Explore the SDK & MCP on GitHub
Mock mode
Your first call, in three commands
You need Node 18 or later and an empty folder. Mock mode is a stateful simulation of the documented lifecycle: a create returns a new id you can read back, and a new party starts unverified, as it does in the sandbox.
Install the SDK
One package, with no runtime dependencies.
Save this file as first-call.mjs
No keys and no environment variables.
Run it
The party comes back ACTIVE with kycStatus VERIFICATION_PENDING, the same starting point as a live integration.
What your terminal prints
Ids and timestamps change on every run.
Next: a whole account in mock mode
The mock-bank example builds an account experience on the SDK with fake data and no credentials. Clone it, run npm install, then npm run dev.
The mock-bank example on GitHub
Test data
Drive each status yourself in mock mode
In mock mode you play the Venly operator. One line approves a verification, credits a EUR IBAN, or settles or fails a transfer, so your code meets each of those states in your own tests.
Mock mode needs no credentials. Sandbox credentials come from Venly and are separate from production credentials.
Every mock driver in the SDK readme
Sandbox
Move the same code to the sandbox
Change the environment to staging and add the Client ID and Client Secret Venly sends you. The SDK fetches, caches and refreshes the token for you. Without the SDK, the quick start is two HTTP calls: exchange your credentials for a token, then create your first party.
With the SDK: change the environment, add credentials
With curl, from the quick start
The quick start in the documentation
Environments
Sandbox and production credentials are separate. The sandbox is the API’s staging environment, and its calls do not move real funds.
From party to first transfer
The statuses between a new customer and money moving
The integration walkthrough takes one customer from a new party to a completed transfer. The step that shapes your design is verification: a party is ACTIVE at once, but its account cannot move money until verification returns VERIFIED.
POST /parties
Create a party
The person or organisation behind the account, INDIVIDUAL or ORGANISATION. It is ACTIVE at once, which is not a verification result.
ACTIVE
POST /accounts
Open an account
Link the party with partyId. Its wallet is provisioned automatically, with no separate call, and the account starts unverified.
VERIFICATION_PENDING
POST /parties/{partyId}/verification
Get the party verified
Mint a hosted verification link and hand it to your customer. The verdict arrives asynchronously, and the account’s kycStatus becomes VERIFIED.
VERIFIED
GET /parties/{partyId}/partner-terms
Partner terms accepted
When the status reads REQUIRED, hand your customer the consent link. Onboarding continues once it reads ACCEPTED.
ACCEPTED
POST /accounts/{accountId}/virtual-bank-accounts
Issue a EUR IBAN
Returns the referenceCode your customer’s bank transfer quotes. The EUR deposit details can arrive a moment later; the VIRTUAL_BANK_ACCOUNT_CREATED webhook tells you when deposits will land. This call takes an idempotencyKey.
ACTIVE
POST /accounts/{accountId}/transfers/crypto
Send a transfer
PENDING while settlement runs, then COMPLETED with a transactionHash, or FAILED with an errorMessage. This call takes an idempotencyKey too.
COMPLETED
The integration walkthrough, step by step
Retries
Retry a money movement without sending it twice
The five operations that create money movement take an idempotencyKey, a UUID you generate, in the request body. It is not a header. Retry with the same key and the operation runs once.
Same key, same body, original succeeded
The original result
Same key, original still in progress
409 idempotency-conflict. Wait, then read again
Same key, different body
422 idempotency-conflict
Same key, original failed
422 idempotency-conflict. Send a new key
A failed original spends its key. To retry after a failure, generate a new one.
Where a key is required
- Create a fiat transfer
- Create a crypto transfer
- Request a pay-out
- Create a virtual bank account
- Create a pay-in session
Keys are unique per company across these operations. Save the key before you send, so a restart retries with the same one.
Idempotency in the documentation
Webhooks
Venly tells your endpoint when something changes
Register one HTTPS endpoint and each state change is pushed to it: pay-ins, transfers, pay-outs, verification verdicts and virtual bank accounts. A ping sends a test event down the real delivery path, including the authentication header your handler checks.
No event carries an amount
An event says what changed. Read amounts and bank details back over the authenticated API.
Every webhook receives every event
Switch on eventType and ignore the types you do not need.
Delivery is at least once
Key your processing on the resource id plus its target status, so a repeat does nothing.
Order is not guaranteed
Compare with the state you hold. A pay-out can go from COMPLETED to RETURNED when the receiving bank sends it back.
Thirteen event types
Webhooks and the event catalogue
Statuses and errors
Documented statuses and error codes you can branch on
Each object has a short, documented lifecycle, and every error carries a stable code. Branch on the code, never the message. Ignore enum values you do not recognise: new values ship without a new API version.
Transfer
PENDING → COMPLETED
Or FAILED, with an errorMessage.
Account verification
VERIFICATION_PENDING → VERIFIED
Read from kycStatus on the account.
Fundflow ramp request
AWAITING_APPROVAL → AWAITING_FUNDS → PROCESSING → SUCCEEDED
Or FAILED, CANCELLED, REJECTED, DENIED or BLOCKED.
A failure returns success: false and a list of errors, each with a code and a message.
The errors every endpoint can return
Malformed body or invalid parameters
Fix the request. Do not retry it unchanged.
Missing or expired token
Refresh the token and retry.
The operation is not available to your company setup
Ask Venly to enable it.
The resource, or one it references, does not exist, for example account-not-found
Check the id.
A stale version on an update
Read the resource again, reapply your change and retry.
An idempotency key reused with a different body, or replaying a call that failed
To retry a real failure, use a new key.
An unexpected server error
Retry with backoff. If it persists, contact Venly.
Not ready yet: the verification gates
A new account cannot move money until it is verified, and each operation reports that with its own code. Treat any of these as not ready yet rather than matching one code.
- Create a virtual bank account
- Create a pay-in session
- Request a pay-out
- Transfer or pay from an inactive self-custody wallet
The Finance API publishes no fixed rate limits. The SDK retries 429, 502, 503 and 504 responses and network errors with exponential backoff and jitter, respects Retry-After and stops after 3 attempts by default. Without the SDK, back off on 500 and on 429, and make each retry safe with an idempotency key.
Throw any of these on purpose in mock mode with failNext, and your handling is tested before the sandbox returns one.
Every error code and what to do
Two APIs
Where each API’s documentation starts
Finance API
Accounts, wallets, USD and EUR receiving details, transfers and pay-outs for your customers.
First call: POST /v1/parties
Fundflow API
Ramp requests that convert your company’s own funds between fiat and stablecoins, with the fee calculated first.
First call: GET /v1/company, which returns your kybStatus
Path to production
From mock mode to live money, and who does each step
Access to the sandbox and to production is not self-serve, because every flow runs on regulated partners and each company is set up for its own coverage. Until then, you can build and test your integration in mock mode.
Build in mock mode
You, today
Your integration, your tests and your failure paths, with no credentials.
Write to us
You
Pick your flow and add a few lines about it.
A scoping call
You and Venly
The API path for your stack, the coverage that applies and a go-live plan.
Sandbox credentials
Venly
Sent to you directly. Switch the environment to staging and run the same code.
Production
Venly and you
Venly sets up your company account, then issues separate production credentials with the scopes for the areas you integrate.
Lead times depend on your flow and its coverage. The scoping call sets them in your go-live plan.
Before your first live call
- Use your production credentials and the production hosts. Sandbox and production credentials are separate.
- Check that your token carries the scope for each area you call. A missing scope returns 403 forbidden.
- Register your production webhook endpoint and send a ping down the real delivery path.
- Save each idempotencyKey before you send, so a restart retries with the same key.
- Handle the verification gate codes as not ready yet, and branch on codes, never on messages.
- Back off with jitter on 500 and 429, and confirm rate limits with your Venly contact if you expect high volumes.
Request sandbox credentials
Details for your engineers
How do I get sandbox credentials?
Venly provisions a Client ID and Client Secret for your company and sends them to you directly. Access is not self-serve: write to us about your flow, and the credentials follow a scoping call.
Do sandbox calls move money?
No. Sandbox calls do not move real funds, and sandbox and production credentials are separate.
Can we try the API before we have sandbox credentials?
Yes. The TypeScript SDK has a mock mode that runs with no credentials and no network. The three commands on this page make your first call.
Can I build with Venly Finance using an AI coding assistant?
Yes. Add the docs MCP server at https://docs.venlyfinance.com/mcp to Claude Code, Codex, Cursor, VS Code or any MCP client. It needs no API key, and it searches the documentation and reads any page, so your assistant works from the current API reference. For an assistant without MCP, give it https://docs.venlyfinance.com/llms-full.txt.
Can my AI agent create test data without credentials?
Yes, in mock mode. The Venly Finance MCP (@venlyfinance/settlement-mcp) gives your agent tools for parties, accounts, receiving details and transfers. Its write tools run only against the mock sandbox, with no credentials and no network, and refuse any other base URL.
Is there an SDK for my language?
The SDK is TypeScript. From any other stack, call the REST API directly; the OpenAPI specs for both APIs are published, so you can generate a client from them.
How long does an access token last?
300 seconds. Request a new token before it expires; a 30-second buffer is enough. A 401 means the token has expired: authenticate again and retry the request once.
Which permissions does my token need?
Each Finance API endpoint requires a scope, such as manage:accounts, manage:transfers or manage:webhooks. Ask Venly to grant the scopes for the areas you integrate. A token without the right scope is rejected with 403 forbidden, not 401.
Are there rate limits?
The Finance API does not publish fixed numeric limits. Cache your token, back off with jitter on a 500 or 429, and confirm the limits with your Venly contact if you expect high volumes.
How are breaking changes handled?
The major version is in the URL (/v1). A breaking change ships as a new major version, announced at least six months before the old one retires, and both run side by side until then.
Authentication, scopes and token refresh
Pagination, versioning and idempotency conventions
Start in mock mode today
When you want the sandbox, tell us what you are building. After a scoping call about your flow, Venly sends your sandbox credentials to you directly.
Request sandbox credentials
Read the documentation
Make your first call
Where your test calls run
Separate credentials per environment. Sandbox and production credentials are issued separately, and sandbox calls move no real funds.
SOC 2 Type 2 certified. Our own licences are in flight and flows run on licensed partner rails today.