Become a wallet provider

The Finance API moves money through wallets. If you don’t have wallet infrastructure yet, you don’t need to go find a custody provider — you can become one yourself with the Venly Wallet API, which issues and secures wallets for your end-users. This page gets you from nothing to a working wallet. It’s self-contained; the full Wallet API reference lives at docs.venly.io.

Do you need this?

You need the Wallet API

You have no wallet infrastructure · you want Venly to generate and secure wallets for your users · you want to issue wallets under your own brand

You can skip it

Your users already hold their own wallets and you’ll register their addresses — that’s self-custody

Which path you’re on is a company-level setting on your Venly tenant, VENLY_MANAGED or SELF_CUSTODY — not a per-request choice. See Venly-managed vs self-custody, and tell your Venly contact which model you want.

Two products, two sets of credentials

Before you start, know that Venly Wallet and Venly Finance are separate products with separate authentication. Mixing up the realm is the single most common early mistake, because the failure looks like bad credentials rather than a wrong URL.

	Wallet API	Finance API
Getting access	Contact Venly	Contact Venly
Credentials live in	portal.venly.io/authentication	Provided by your Venly contact
Token endpoint realm	`Arkane`	`VenlyFinance`
Production token URL	`https://login.venly.io/auth/realms/Arkane/protocol/openid-connect/token`	`https://login.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token`
API base URL	`https://api-wallet.venly.io`	`https://api.venlyfinance.com/v1`
Token lifetime	~6 minutes	~5 minutes

Both use OAuth2 client_credentials. A Wallet API token will not authenticate a Finance API call, and vice versa — you’ll hold two tokens.

Get access and credentials

Venly Wallet API access is not self-serve. There is no public signup — you request access and Venly provisions your account.

Request access

Get in touch with Venly to have a business account provisioned. Tell them you want Wallet API access, and mention if you also need the Finance API — the two are provisioned separately.Once your account exists you’ll be able to sign in to portal.venly.io, where your credentials live.

Copy your client credentials

Go to the authentication section of the portal (portal.venly.io/authentication) and copy your Client ID and Client Secret.There are two sets, switched with a toggle:

	Use for
Sandbox	Testnets. Start here.
Production	Mainnet. Real value.

The client secret is a credential — keep it server-side. Never ship it in a browser bundle, mobile app, or public repository.

Get a bearer token

curl -X POST https://login-sandbox.venly.io/auth/realms/Arkane/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Then send it on every call:

Authorization: Bearer {access_token}

Tokens last about 6 minutes. Cache the token and refresh on expiry — don’t fetch a new one per request. A refresh_token is returned but is deprecated; just request a new token.

Issue your first wallet

Three Wallet API concepts, and they nest in this order: A user is one of your end-users. A signing method is how that user authorises actions. A wallet belongs to a user and needs a signing method to create. Sandbox base URL: https://api-wallet-sandbox.venly.io

Create a user

curl -X POST https://api-wallet-sandbox.venly.io/api/users \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "reference": "user-12345" }'

Keep result.id — that’s your userId. Use your own identifier as the reference so you can reconcile against your user table.

Create a signing method

curl -X POST https://api-wallet-sandbox.venly.io/api/users/{userId}/signing-methods \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "type": "PIN", "value": "123456" }'

Keep result.id — that’s your signingMethodId.

A PIN is the user’s authorisation secret. In production, collect it from the user; never hard-code one or reuse a default across users.

Create a wallet

curl -X POST https://api-wallet-sandbox.venly.io/api/wallets \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Signing-Method: {signingMethodId}:123456" \
  -d '{ "secretType": "BASE", "userId": "{userId}" }'

Note the Signing-Method header — {signingMethodId}:{pinValue}. Wallet creation needs the user’s authorisation, so this isn’t optional.Keep result.id and result.address.

Your sandbox tenant may already contain a testnet user and wallet preloaded with test assets, so check before creating your own — list what’s there with GET /api/users?includeSigningMethods=true and GET /api/wallets?userId={userId}.

`secretType` and chain names

The Wallet API names chains with secretType, and a few differ from the Finance API’s chain values. Translate when you cross between the two products:

Finance API `chain`	Wallet API `secretType`
`BASE`	`BASE`
`ETHEREUM`	`ETHEREUM`
`AVALANCHE`	`AVAC`
`POLYGON`	`MATIC`
`ARBITRUM`	`ARBITRUM`
`OPTIMISM`	`OPTIMISM`
`BSC`	`BSC`

The Wallet API supports more chains than the Finance API settles on — see Supported chains & assets for what Finance accepts.

Connecting it to the Finance API

With wallets in hand, you’re a wallet provider. Now wire it to Venly Finance:

Ask Venly to set your wallet type

Tell your Venly contact whether your Finance tenant should be VENLY_MANAGED (Venly generates wallets for accounts) or SELF_CUSTODY (you supply addresses). If you’re issuing wallets through the Wallet API yourself and registering those addresses, that’s SELF_CUSTODY.

Create a party and an account

Follow the Finance API quickstart. For SELF_CUSTODY, pass the wallet address you got above when creating the account.

Verify the party

Send the party through verification before attempting to move money.

Sign the permit (self-custody)

A self-custody wallet needs a one-time signed permit before Venly can move its funds. You sign it with the wallet you just created — via the Wallet API’s signing endpoints, using that user’s signing method.

Next steps

Wallet API documentation

The full reference — users, signing methods, wallets, balances, transactions, signing.

Wallet API quickstart

Venly’s own getting-started guide, in more depth.

Venly-managed vs self-custody

Which custody model your Finance tenant should use.

Finance API quickstart

Party → account → verification → bank rails.

​Do you need this?

You need the Wallet API

You can skip it

​Two products, two sets of credentials

​Get access and credentials

​Issue your first wallet

​secretType and chain names

​Connecting it to the Finance API

​Next steps

Wallet API documentation

Wallet API quickstart

Venly-managed vs self-custody

Finance API quickstart

Do you need this?

Two products, two sets of credentials

Get access and credentials

Issue your first wallet

`secretType` and chain names

Connecting it to the Finance API

Next steps