Create a wallet

Creates a custodial wallet under the association resolved from the token. Only walletName and assetCode are accepted — network, wallet type, and custody are fixed platform-side. assetCode funds the wallet and establishes the asset trustline. Balances are attached best-effort on the response.

This creates a real, permanently persisted wallet — including real on-chain funding — even when called with sandbox credentials. Sandbox only simulates off-ramp payout execution; it does not sandbox record creation.

POST /wallets

Create a wallet

cURL

curl --request POST \
  --url https://api.zeam.money/gw/v1/wallets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-zeam-auth: <api-key>' \
  --data '
{
  "walletName": "Treasury USDZ",
  "assetCode": "USDZ"
}
'

201

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "publicKey": "<string>",
  "walletName": "<string>",
  "accountNumber": "<string>",
  "networkName": "<string>",
  "hasMultipleSigners": true,
  "ownAccount": true,
  "status": "Pending",
  "balances": [
    {
      "assetCode": "USDZ",
      "balance": "1250.0000000"
    }
  ]
}

Authorizations

Authorization · string · header · required

Access token issued by POST /v1/auth/token.

x-zeam-auth · string · header · required

Application secret (the apiKey issued at registration), required on every request.

Body

application/json

walletName · string · required

assetCode · string · required

Asset code for the initial trustline (e.g. USDZ). Discover valid codes via GET /v1/assets.

ownAccount · boolean · default: false

Whether the wallet belongs to your own business. When false, metadata is required and the wallet starts in status Pending until its KYC review completes.

metadata · object

Third-party FICA details. Required when ownAccount is false; must be omitted when true.

Show child attributes

Response

201

application/json

Wallet created.

id · string<uuid> · required

publicKey · string · required

Stellar public key (G...)

walletName · string

accountNumber · string

Zeam account number.

networkName · string

Platform network name.

hasMultipleSigners · boolean

ownAccount · boolean

Whether the wallet belongs to the association's own business (false = held on behalf of a third party).

status · enum<string>

Verification status. Only a Verified wallet may be transacted on; own-account wallets are Verified at creation, third-party wallets start Pending until their KYC review completes.

Available options: Pending, Verified, Rejected

balances · object[] | null

On-chain balances. Populated best-effort; null when the balance lookup failed. Native XLM is excluded.

Show child attributes