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

# Become a wallet provider

> No wallet infrastructure? Request Venly Wallet API access and issue wallets to your own users.

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](https://docs.venly.io/docs/wallet-api-overview).

## Do you need this?

<CardGroup cols={2}>
  <Card title="You need the Wallet API" icon="circle-check">
    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
  </Card>

  <Card title="You can skip it" icon="circle-minus">
    Your users already hold their own wallets and you'll register their addresses — that's
    [self-custody](/guides/finance/managed-vs-self-custody)
  </Card>
</CardGroup>

<Note>
  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](/guides/finance/managed-vs-self-custody), and tell your Venly contact
  which model you want.
</Note>

## 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](https://venlyfinance.com/contact)                         | [Contact Venly](https://venlyfinance.com/contact)                               |
| Credentials live in  | [portal.venly.io/authentication](https://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

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

<Steps>
  <Step title="Request access">
    [Get in touch with Venly](https://venlyfinance.com/contact) to have a business account provisioned.
    Tell them you want Wallet API access, and mention if you also need the
    [Finance API](/api-reference/introduction) — the two are provisioned separately.

    Once your account exists you'll be able to sign in to
    [portal.venly.io](https://portal.venly.io/), where your credentials live.
  </Step>

  <Step title="Copy your client credentials">
    Go to the authentication section of the portal
    ([portal.venly.io/authentication](https://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.  |

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

  <Step title="Get a bearer token">
    ```bash theme={null}
    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.
  </Step>
</Steps>

## Issue your first wallet

Three Wallet API concepts, and they nest in this order:

```mermaid theme={null}
flowchart LR
    U["User<br/><i>your end-user</i>"] --> S["Signing method<br/><i>e.g. a PIN</i>"]
    S --> W["Wallet<br/><i>one per chain</i>"]
```

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`

<Steps>
  <Step title="Create a user">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Create a signing method">
    ```bash theme={null}
    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`.

    <Warning>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.</Warning>
  </Step>

  <Step title="Create a wallet">
    ```bash theme={null}
    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`.
  </Step>
</Steps>

<Note>
  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}`.
</Note>

### `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](/guides/finance/supported-chains-and-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:

<Steps>
  <Step title="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`.
  </Step>

  <Step title="Create a party and an account">
    Follow the [Finance API quickstart](/getting-started/quickstart). For `SELF_CUSTODY`, pass the
    wallet `address` you got above when
    [creating the account](/api-reference/Finance-API/accounts/create-a-new-account).
  </Step>

  <Step title="Verify the party">
    Send the party through [verification](/guides/finance/onboarding/lifecycle) before attempting to
    move money.
  </Step>

  <Step title="Sign the permit (self-custody)">
    A self-custody wallet needs a one-time signed [permit](/guides/finance/permits-and-allowances)
    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.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Wallet API documentation" icon="book" href="https://docs.venly.io/docs/wallet-api-overview">
    The full reference — users, signing methods, wallets, balances, transactions, signing.
  </Card>

  <Card title="Wallet API quickstart" icon="rocket" href="https://docs.venly.io/docs/wallet-api-getting-started">
    Venly's own getting-started guide, in more depth.
  </Card>

  <Card title="Venly-managed vs self-custody" icon="key" href="/guides/finance/managed-vs-self-custody">
    Which custody model your Finance tenant should use.
  </Card>

  <Card title="Finance API quickstart" icon="play" href="/getting-started/quickstart">
    Party → account → verification → bank rails.
  </Card>
</CardGroup>