What a wallet is for
Two things, and they pull in different directions.Receiving — the address
address on its network. That is an
ordinary on-chain transfer; nothing about it is Endl-specific.Settling — the destination
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.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 gets403 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.
Networks
Nine networks are supported: six mainnets, and three test networks on test environments.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.Creating a wallet
Create the customer and get them verified
cus_…
reference id — that is the {userId} in every wallets path — and see them
through KYC.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.userId in the body is stripped and ignored — the customer is the one in
the path, and only the one in the path.Read the id and address off the response
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.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 awlt_… 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.
400 ERRWLT_1003.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.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.type: "EXTERNAL", and wallet.created fires just
as it does for a custodial wallet.
409 ERRWLT_1009 — EVM addresses compared
case-insensitively, TRON exactly. A different customer may register the same address.What it can and cannot do
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.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.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.403 ERRWLT_1013), and only EVM wallets
can receive the tokens: a TronNile wallet is 400 ERRWLT_1003.Updating and deleting
Update takesname, 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.
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.
404 ERRREF_1001, field userId. A blank userId is 400 ERRCORE_1001 (userId is required, field null).
Error handling
Wallet-specific failures carry anERRWLT_ code. Everything cross-cutting —
validation, auth, rate limiting — uses the shared ERRCORE_ codes described in
Errors and the response envelope.
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.
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
Create wallet returns 400 'network must be one of…' but my network is in the list
Create wallet returns 400 'network must be one of…' but my network is in the list
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.The same create call works in production and fails in sandbox
The same create call works in production and fails in sandbox
BaseSepolia rather than Base.Create wallet returns 403 and the key definitely has the wallets permission
Create wallet returns 403 and the key definitely has the wallets permission
ERRWLT_1005 is the KYC gate, not a permission failure. The customer has not
completed verification. A permission failure is ERRCORE_1005.A wallet says currency USDC, but it holds USDT
A wallet says currency USDC, but it holds USDT
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.Get wallet returns 404 for a wallet that is definitely there
Get wallet returns 404 for a wallet that is definitely there
wlt_ reference is well-formed but
unknown. Check List wallets for that customer.Delete returned 200 and I was expecting 204
Delete returned 200 and I was expecting 204
200 with status: "deleted". Nothing in the v0 surface
returns an empty 204.I deleted a wallet that still had a balance
I deleted a wallet that still had a balance
Do I need a separate wallet for each chain?
Do I need a separate wallet for each chain?
Glossary
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.