> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Read your assets and balances, find where to send money, send a payout, and convert.

<Warning>
  This guide uses the production URL. Step 4 and step 5 move real money. To
  test safely, use the sandbox base URL `api.sandbox.jenzy.com`. See
  [Sandbox](/v2/sandbox).
</Warning>

<Steps>
  <Step title="Read your assets">
    Put your `jz_live_…` API key in the `Authorization` header of each
    request. `GET /v2/assets` lists the assets that Jenzy enabled for your
    org, with the operations that you can do in each.

    ```bash theme={null}
    curl https://api.jenzy.com/v2/assets \
      -H "Authorization: Bearer $JENZY_API_KEY"
    ```

    ```json theme={null}
    {
      "assets": [
        { "asset": "KES", "decimals": 2, "operations": ["payout", "convert", "collection"] },
        { "asset": "USDT", "decimals": 6, "operations": ["payout", "convert", "collection"] }
      ]
    }
    ```

    An asset that is not in the list does not exist for your org. A request
    in that asset gets `corridor_not_enabled`. Speak to Jenzy to enable a
    new asset.
  </Step>

  <Step title="Read your balances">
    Each asset has its own balance. `GET /v2/balances` gives one row for
    each asset in step 1. There is no total.

    ```bash theme={null}
    curl https://api.jenzy.com/v2/balances \
      -H "Authorization: Bearer $JENZY_API_KEY"
    ```

    ```json theme={null}
    {
      "balances": [
        { "asset": "KES", "available": "1250000.00", "held": "50000.00", "shortfall": "0.00" },
        { "asset": "USDT", "available": "820.5", "held": "0", "shortfall": "0" }
      ]
    }
    ```

    `available` is the money that you can spend now. `held` is the money
    that payouts in progress reserve. See [Balances](/v2/balances).
  </Step>

  <Step title="Find where to send money">
    To fund a fiat balance, read your virtual account for that asset. Give
    the details to the person who pays you.

    ```bash theme={null}
    curl "https://api.jenzy.com/v2/virtual-accounts?asset=KES" \
      -H "Authorization: Bearer $JENZY_API_KEY"
    ```

    To fund a stablecoin balance, ask for a deposit address on a network.
    The same address takes each stablecoin on that network.

    ```bash theme={null}
    curl -X POST https://api.jenzy.com/v2/deposit-addresses \
      -H "Authorization: Bearer $JENZY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "network": "tron" }'
    ```

    ```json theme={null}
    { "network": "tron", "address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9", "assets": ["USDT"] }
    ```

    Money that arrives becomes a collection. Hermes credits your balance and
    sends `collection.settled` to your webhook endpoint. See
    [Collections](/v2/collections).
  </Step>

  <Step title="Send a payout">
    One endpoint pays every destination. The `type` field of the
    `destination` object selects the rail. `amount` and `asset` are always
    what the beneficiary receives.

    Each create request needs an **`Idempotency-Key`** header. Make one key
    for each payout that you intend to send. You can use a UUID. A request
    with no key gets `400`.

    ```bash theme={null}
    curl -X POST https://api.jenzy.com/v2/payouts \
      -H "Authorization: Bearer $JENZY_API_KEY" \
      -H "Idempotency-Key: 9f1c7a58-6f2d-4b0e-9d2e-3f8a1c5b7e42" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": "10000.00",
        "asset": "KES",
        "destination": {
          "type": "momo",
          "institution_id": "kes-momo-m-pesa",
          "mobile_number": "+254712345678",
          "beneficiary_name": "Jane Doe"
        }
      }'
    ```

    `institution_id` comes from `GET /v2/institutions?asset=KES`. A mobile
    number is in E.164 form, with the `+`. Hermes refuses a number in a
    different form. Hermes does not correct the number for you.

    A `201` response is the payout. Hermes holds the money at once.

    ```json theme={null}
    {
      "id": "0d5e63b2-59f3-4d2a-8f57-2f14a3c14f6d",
      "status": "pending",
      "asset": "KES",
      "amount": "10000.00",
      "source_asset": "KES",
      "source_amount": "10000.00",
      "fee": "50.00",
      "rate": null,
      "destination": {
        "type": "momo",
        "institution_id": "kes-momo-m-pesa",
        "mobile_number": "+254712345678",
        "beneficiary_name": "Jane Doe"
      },
      "failure": null,
      "created_at": "2026-09-09T09:14:02.000Z",
      "terminal_at": null
    }
    ```

    A `4xx` response means that **Hermes made no payout and held no money**.
    A `201` response can already show `status: "failed"`. See
    [Payouts](/v2/payouts) for the reason.
  </Step>

  <Step title="Convert between assets">
    First get a quote. Then execute the quote. `to_amount` is what you
    receive, and Hermes does not change it.

    A conversion is always between one fiat asset and one stablecoin, in
    either direction. Hermes does not support fiat to fiat, or stablecoin to
    stablecoin, for now. Such a pair gets `unsupported_pair` (422).

    ```bash theme={null}
    curl -X POST https://api.jenzy.com/v2/conversions/quotes \
      -H "Authorization: Bearer $JENZY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "from_asset": "USDT", "to_asset": "KES", "from_amount": "100" }'
    ```

    ```json theme={null}
    {
      "quote_id": "3e7c1b7a-0b1e-4b8f-9d2a-6f1c2e3d4a5b",
      "from_asset": "USDT",
      "to_asset": "KES",
      "from_amount": "100",
      "to_amount": "12840.00",
      "rate": "0.00778816",
      "expires_at": "2026-09-09T10:00:25.000Z"
    }
    ```

    Execute before `expires_at`. The execute request needs an
    `Idempotency-Key`.

    ```bash theme={null}
    curl -X POST https://api.jenzy.com/v2/conversions \
      -H "Authorization: Bearer $JENZY_API_KEY" \
      -H "Idempotency-Key: 5b2d8c1e-7f3a-4e9b-8c6d-1a2b3c4d5e6f" \
      -H "Content-Type: application/json" \
      -d '{ "quote_id": "3e7c1b7a-0b1e-4b8f-9d2a-6f1c2e3d4a5b" }'
    ```

    The response is the conversion, with `status: "completed"` in the
    normal case. See [Conversions](/v2/conversions).
  </Step>

  <Step title="Learn the result">
    A payout is terminal when `status` is `succeeded` or `failed`. There are
    two ways to learn the result.

    **Webhooks (recommended)** — Hermes sends `payout.succeeded` or
    `payout.failed` to your endpoint. The delivery carries
    `api_version: "v2"`. See [Webhooks](/webhooks).

    **A poll** — read `GET /v2/payouts/{id}` again until the status is
    terminal.

    When a payout fails, Hermes releases the hold back to `available`.
    Hermes never sends a failed payout again. To try again, create a **new**
    payout with a **new** `Idempotency-Key`.
  </Step>
</Steps>

That is the full loop. See [Payouts](/v2/payouts) for the FX payout, the
status lifecycle, and the limits.