Skip to main content
A wallet is where your customer’s stablecoin actually sits. Endl custodies the keys; you never handle them, and there is no seed phrase to show anyone. What you get back is an address, and that address is the thing you give to whoever is sending crypto.
One EVM wallet works across all five EVM networks. Creating an EVM wallet gives you a single wallet ID that works across Ethereum, Polygon, Base, Arbitrum and Optimism. You don’t need to create a separate wallet for each chain — one wallet ID and address is valid on all of them.Tron is not one of the five, so receiving on Tron needs its own Tron wallet.
This is the conceptual guide. For the endpoints themselves — parameters, schemas and worked bodies — see the Wallets API reference.

What a wallet is for

Two things, and they pull in different directions.

Receiving — the address

Somebody sends stablecoin to the wallet’s address on its network. That is an ordinary on-chain transfer; nothing about it is Endl-specific.

Settling — the destination

An ONRAMP account converts a fiat deposit and settles the stablecoin into a wallet. That is why walletId is required when you open one — the wallet supplies the settlement asset, chain and address.
The second is the common case. Most partners create one EVM wallet per customer and then point every ONRAMP account at it.

Who may create one

The customer must have completed KYC. Create is gated on it; everything else — list, get, balance, update, delete — is not. An incomplete customer gets 403 ERRWLT_1005, and the check is the same completion rule the rest of the platform uses, so a customer who can transact can create a wallet.
The gate is on completion, not on having started. A customer sitting in PENDING or UNDER_REVIEW fails it exactly like one who never began. Create the customer and get them through verification before you try to open a wallet for them.

Networks

Nine networks are supported: six mainnets, and three test networks on test environments.
network is matched case-sensitively when you create a wallet. Base is accepted; base and BASE are rejected with network must be one of: …. Copy the spelling out of the table above exactly.Confusingly, the same names are matched case-insensitively everywhere else — reading a balance for :chain, naming a network on a transfer. Only creation is strict. Treat the canonical casing as the only correct form and the inconsistency never bites you.
Each environment accepts only one column of this table. Production and staging accept the six mainnets; sandbox and QA accept the three test networks. So a Base wallet that works in production is refused in sandbox, where you would create a BaseSepolia one instead. The error message lists the networks the environment you are calling actually allows — read it rather than assuming.
Quotes spell these networks differently — see the mapping table.

Creating a wallet

1

Create the customer and get them verified

Wallets hang off a customer. Create one, keep its cus_… reference id — that is the {userId} in every wallets path — and see them through KYC.
2

POST the network

network is the only required field. name is optional but must be a non-empty string if you send it at all, and tags must be an array of strings if present.
Request
A userId in the body is stripped and ignored — the customer is the one in the path, and only the one in the path.
3

Read the id and address off the response

The response carries the wallet’s walletId (a wlt_… reference), its address, its network and a status. The address is live from that moment; there is no activation step.

What comes back

Create, Get, Update and List wallets all return the same wallet object.
currency is not a restriction. Every wallet is recorded locally with a default currency stamped at creation — USDT on a Tron wallet (Tron or TronNile), USDC on every other network. It does not mean the wallet can only hold that currency, and it is not derived from what is actually on-chain. For what the wallet really holds, call Get wallet balance.
The cryptographic material behind the wallet — public key, scheme, curve — is deliberately not in the response. If you are looking for a signingKey block because you saw one in a custody provider’s own docs, it is removed on purpose and will not be added.

External wallets

An external wallet is an address the customer already holds themselves — in their own self-custody wallet or at another custodian. Nothing is created at any provider: Endl registers the address you send and gives it a wlt_… id like any other wallet. Use one when the customer wants onramp proceeds settled to their own wallet. Open an ONRAMP account with the external wallet’s walletId, and the stablecoin from each fiat deposit lands on the customer’s address rather than on a wallet Endl holds.

Registering one

Same endpoint, same KYC gate (403 ERRWLT_1005). Send type: "EXTERNAL" (case-insensitive) with the network and the customer’s address.
string
CUSTODIAL (the default when omitted) or EXTERNAL. Anything else is 400 ERRWLT_1007.
string
required
The same networks a custodial wallet may be created on in this environment, EVM and TRON families. Unlike custodial create, matched case-insensitively. Otherwise 400 ERRWLT_1003.
string
required
EVM networks: 0x + 40 hex characters. TRON networks: T + 33 base58-style characters. Trimmed; case preserved — TRON addresses are case-sensitive. Missing or malformed is 400 ERRWLT_1008.
string
USDC or USDT, and the network must carry it: TRON is USDT-only; Polygon, Base, Arbitrum and Optimism are USDC-only; Ethereum carries both. Defaults to USDC, or USDT on TRON. Otherwise 400 ERRWLT_1010. Choose it deliberately — it is the settlement asset for accounts that settle to this wallet.
string
Optional label; a non-empty string if sent. tags are not used for external wallets.
The response is the ordinary wallet object with type: "EXTERNAL", and wallet.created fires just as it does for a custodial wallet.
Duplicates are per customer, per network. Registering an address the same customer already has as an active wallet on the same network is 409 ERRWLT_1009 — EVM addresses compared case-insensitively, TRON exactly. A different customer may register the same address.

What it can and cannot do

An external wallet is a settlement destination only. Endl never sees the key, so it cannot read, move or sweep what is on the address — the customer manages those funds in their own wallet. Anything that moves money out of a wallet needs a custodial one.
AED and TRON. When an AED account is opened against a TRON wallet without a chainCode, the wallet’s own chain is used. A chainCode from the other address family than the wallet is 400 ERRACC_1008.

Reading balances

Get wallet balance returns the wallet’s native asset, its tokens and a USD total. For most networks the call aggregates across chains in one request. TRON is the exception: TRON balances are queried on their own chain because they are not covered by the aggregate. You do not have to do anything about this — Endl picks the right query from the wallet’s network — but it does mean a TRON wallet’s balance reflects TRON only, while an EVM wallet’s can span the networks its key covers.
The balance body names the wallet under walletId, and that value is rewritten to your wlt_… reference before it reaches you. Everything else in the body — address, chain, native, tokens, totalUsd — is on-chain data and passes through untouched.
Sandbox only: a newly created EVM wallet already holds 100 test USDC and 100 test USDT on its network when you first call Get wallet balance. This is sandbox-only seed funding, not production behaviour.

Funding a sandbox wallet

To top a sandbox wallet up — after your tests spend the seed funds, for example — call Mint test tokens. It mints up to 10 test USDC and 10 test USDT per call on Base Sepolia, into a custodial EVM wallet, with no help from Endl needed. Then read the new balance with Get wallet balance.
Mint test tokens is refused in production (403 ERRWLT_1013), and only EVM wallets can receive the tokens: a TronNile wallet is 400 ERRWLT_1003.

Updating and deleting

Update takes name, externalId, or both. Sending neither is a 400 — a no-op update is treated as a mistake rather than quietly accepted. Only name is mirrored into Endl’s own record; externalId lives at the custody layer. An external wallet can only be renamed: name is required and is the only field that changes. Delete is soft, and it is one-way through this API.
A wallet that accounts settle to cannot be deleted. While any live account names the wallet as its settlement destination, delete is refused with 409 ERRWLT_1012 on field walletId. “Live” is any account status other than CLOSED or deactivated — an account still being created counts. Close or deactivate those accounts first, or move them to another wallet with Update account — protection follows the account, so the new wallet becomes protected and the old one can be deleted once nothing else settles to it. This applies to every wallet, custodial and external.
A deleted wallet does not vanish, and deleting it does not move any funds. It is hidden from the API, not destroyed — the wallet still exists on-chain, at the same address.
  • It stops appearing in List wallets.
  • Get wallet returns 404 ERRWLT_1000, even though the record still exists.
  • The response is 200 with status: "deleted" — not an empty 204.
  • It is not idempotent. A second delete of the same wallet answers 404 ERRWLT_1000, not another 200.
Sweep any balance out before you delete. There is no undelete endpoint.

Scoping and reference ids

Every wallets path is /{userId}/…, and the customer is resolved from that path segment alone. A wallet that belongs to a different customer is reported as 404 ERRWLT_1000 — never 403 — so a partner can never probe which wallet ids exist under another customer. Raw UUIDs are not accepted in either position. A customer id that isn’t blank but doesn’t resolve — malformed, unknown, deleted or another partner’s — is always 404 ERRREF_1001, field userId. A blank userId is 400 ERRCORE_1001 (userId is required, field null).

Error handling

Wallet-specific failures carry an ERRWLT_ code. Everything cross-cutting — validation, auth, rate limiting — uses the shared ERRCORE_ codes described in Errors and the response envelope. A bad wallet reference is not a wallet error: a malformed wlt_… is 400 ERRREF_1000, and an unknown one is 404 ERRREF_1001. A missing network on Create wallet is ERRCORE_1001; a present but unusable one is ERRWLT_1003. ERRWLT_1001, 1002 and 1004 exist but are not raised on /api/v0. Only ERRWLT_1006 is retryable. Branch on the code, never on the message text — the codes are frozen and will never be renumbered or reused; the wording may be refined at any time.

Webhooks

Wallets produce two events. Delivery, signing, replay protection and the envelope shape are covered in the Webhooks guide — this is only what is specific to wallets. data.id is the wallet’s wlt_… reference. The payload body is deliberately thin — network, currency and type (CUSTODIAL or EXTERNAL), nothing else. See Wallet events for examples.
Both events are best-effort, and both are emitted after the work has already succeeded. If the emit fails the wallet still exists (or is still deleted) — the API response is the authority, not the event.
There is also no wallet.updated. Renaming a wallet emits nothing, and so does money arriving: an incoming on-chain transfer is a deposit event, not a wallet event.

Common pitfalls

Check the casing. Creation matches network exactly: Base, not base. Everything else in the API is case-insensitive about network names, which is what makes this one easy to miss.
Sandbox and QA restrict creation to test networks. The error lists the networks that environment allows — BaseSepolia rather than Base.
ERRWLT_1005 is the KYC gate, not a permission failure. The customer has not completed verification. A permission failure is ERRCORE_1005.
currency is a local default stamped at creation — USDT on a Tron wallet, USDC on every other network — not a reading of the chain and not a restriction on the wallet. Use Get wallet balance for holdings.
Three possibilities, all reported identically on purpose: it was deleted, it belongs to a different customer, or the wlt_ reference is well-formed but unknown. Check List wallets for that customer.
Delete returns a body — 200 with status: "deleted". Nothing in the v0 surface returns an empty 204.
The delete succeeded and the funds did not move. Deletion is a bookkeeping operation, not a sweep. Contact Endl — there is no undelete endpoint.
For the EVM chains, that is what an EVM wallet already is: one wallet ID and one address, valid on Ethereum, Polygon, Base, Arbitrum and Optimism. You don’t need a wallet per chain. Tron is separate — create a Tron wallet to receive on Tron.

Glossary

Written against Api-Version: 2026-09.1. The network list is platform-wide; what a given environment and a given customer can actually use is narrower, so read errors rather than hardcoding this page.