---
title: "Create a client wallet"
method: POST
path: "/wallet"
tags: ["Wallet"]
---

# Create a client wallet

`POST /wallet`

## Request

- Base URL: `https://api.masspay.io/v1.0.0`
- URL: `https://api.masspay.io/v1.0.0/wallet`
- Auth: one of:
  - API key in header `Authorization`
  - API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/masspay/apis/masspay-api/docs/wallet/post.ts> (a function with typed inputs; its response is checked against the schema)

This **POST** endpoint creates a new wallet for your own client account, in the requested currency. <br> To use this endpoint, you need to provide the `currency_code` as a JSON parameter in the Request Body. It must be an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, such as `USD`, `EUR` or `MXN`. <br> A client can hold at most one wallet per currency, so the operation is idempotent: if you already have a wallet in the requested currency, that existing wallet is returned unchanged with a `200` status code instead of `201`, and its `balance` reflects the current balance. <br> Newly created wallets start with a zero balance and can be funded through top-ups, pay-ins or wallet transfers. Client wallets are listed by the **GET** operation on `/payout/account/balance`. <br> A client wallet in a currency you have not funded payouts from before may need to be linked to a liquidity provider by MassPay before it can fund payouts; contact your account manager after creating one.

## Headers

- `Idempotency-Key` string

## Request body

- ClientWalletCreateReq: Request body for creating a wallet for your own client account.
  - `currency_code` string, required: Currency the wallet is denominated in, using the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. Case-insensitive.

## Response `200`

You already have a wallet in the requested currency; the existing wallet is returned and nothing is created.

- WalletCreateResp: The wallet created by a wallet creation request, or the owner's existing wallet in that currency when one already existed. User wallets carry the same fields as the wallets returned by the user wallet listing.
  - `token` string, required: Prefixed wallet identifier. User wallets use the `usr_wlt_` prefix and client wallets use the `clnt_wlt_` prefix.
  - `type` 'USER_FUNDS' | 'CLIENT_FUNDS', required: Type of wallet: `USER_FUNDS` when created for a user, `CLIENT_FUNDS` when created for the client account.
  - `user_token` string: Token representing the user who owns the wallet. Present only for `USER_FUNDS` wallets.
  - `currency_code` string, required: Currency the wallet balance is stored in, using the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.
  - `balance` number, required: The wallet's current balance in `currency_code`. Zero for a newly created wallet.
  - `active` boolean, required: An indicator whether the wallet is active.
  - `client_paying_fees` boolean, required: An indicator whether the fees for payouts using this wallet are paid by a client wallet. If false, the user pays the fees. Always false for `CLIENT_FUNDS` wallets.
  - `fee_wallet_token` string: Token of your client wallet that pays the fees for payouts using this wallet. Present only when `client_paying_fees` is true and the fee-paying wallet belongs to the authenticated client.

## Other responses

- `201`: Successfully created.
- `400`: Bad request.
- `401`: Unauthorized.
- `403`: Forbidden.
- `405`: Method Not Allowed.
- `500`: Internal server error.
- `504`: Gateway Time-out.

## Changes

- **2026-11-03** `f9fa41b7c45c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/masspay/apis/masspay-api/changes/wallet/post.md)

---

[API](https://skmtc.dev/masspay/apis/masspay-api.md) - [All operations](https://skmtc.dev/masspay/apis/masspay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/masspay/apis/masspay-api/revisions/f9fa41b7c45c?raw)