List wallets
GET/wallets●Query wallets with filtering, sorting, and pagination.
Use this endpoint to review accounts in the system. Wallets can model bank accounts, loyalty cards, bills, or any concept that carries a balance — the handle is typically an account number or other user-friendly identifier.
Supported filters:
data.schema— wallet schemadata.bridge— assigned bridgemeta.status— record statusmeta.labels— record labelsmeta.domain— domain scopedata.custom.<field>— any custom field (may be slower on large datasets)
Usage Examples
curl -X GET "http://localhost:3000/v2/wallets" \ -H "x-ledger: <YOUR LEDGER HANDLE>"{
"hash": "9a408586c772ea13552a87dca52280eea555079b2c03635c5800fa439c2a185c",
"data": [
{
"luid": "$wlt.-01xK9pStU3eT5xY4",
"hash": "0c91fa00006ddaf9476992370ba7209b4815f974d57fa1340e7b194afe37863b",
"data": {
"handle": "tesla-bank-wallet",
"custom": {
"name": "Tesla Bank Wallet",
"description": "Primary wallet for Tesla Bank"
}
},
"meta": {
"status": "created",
"moment": "2025-04-05T14:30:00.050Z",
"owners": [
"dsZvr0rEw9sIffHlv1VP65x1NB8GeXezIv6HONk1SIk="
],
"proofs": [
{
"signer": "tesla-bank-admin",
"method": "ed25519-v2",
"digest": "ae6506402682b12e805b1d75cf3997f18b41e5a24eb318fb223b7e5e39ca40ed",
"public": "dsZvr0rEw9sIffHlv1VP65x1NB8GeXezIv6HONk1SIk=",
"result": "0H17ehu2rXMaNKwqV7l2EDe1VGqJbOgCFCq+8D5tVsz1qp7D6TXjfNTatijNpFi7nLlYf+LhlqLLnVSm1aMVAA==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z",
"status": "created"
}
},
{
"signer": "system",
"method": "ed25519-v2",
"digest": "75545655dad3c6ac9a9e7552262de308ed18e7377d6d4fe273d2254c86a9e5a3",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "4NdQ4MSg7RoHtBEX8lUe9uxfNgfhcHLybvFyNLBzlJy7s78mBPxjCjErn7YQX4vxGdkm3zcpo+4bkJejO2oUDQ==",
"custom": {
"luid": "$wlt.-01xK9pStU3eT5xY4",
"moment": "2025-04-05T14:30:00.050Z",
"status": "created"
}
}
]
}
},
{
"luid": "$wlt.-01xG49X4seDD6yZT",
"hash": "f3ddf0b88ff2286b94d362a061fdf176be43b1d43a4108a820bf2b908fd6c734",
"data": {
"handle": "nova-bank-wallet",
"parent": "0c91fa00006ddaf9476992370ba7209b4815f974d57fa1340e7b194afe37863b",
"custom": {
"name": "Nova Bank Wallet",
"description": "Participant wallet for Nova Bank"
}
},
"meta": {
"status": "created",
"moment": "2025-04-05T14:21:40.025Z",
"owners": [
"i90xMpGuWFGxnnKRX/7slzF/vH+1XW2UcAl/e7kUKa0="
],
"proofs": [
{
"signer": "nova-bank-admin",
"method": "ed25519-v2",
"digest": "58bd7f82f0e5f628bb00e377e7d5aa108de958f0a00a71e911f29c68698cb768",
"public": "i90xMpGuWFGxnnKRX/7slzF/vH+1XW2UcAl/e7kUKa0=",
"result": "rc7UmWikd8wvliVvFPgRHyVhzlRZoje1JYChB4Y98PeawK2fhcE64/CjwlovgdTu4SiGs0keYpgoYUBq6FE4Bw==",
"custom": {
"moment": "2025-04-05T14:21:40.000Z",
"status": "created"
}
},
{
"signer": "system",
"method": "ed25519-v2",
"digest": "6d6ef1e91c08426733091f9adf4e6443ac9bd2aaa07eab29a39717032f91a4fa",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "cpCw1Jp+RGedJAKqKkucS5m2GvbtZvnrDz7wSo+wCbPObYqnOte6934BVRMdNbbbKp750xxEEp2KZRPvbAVtAQ==",
"custom": {
"luid": "$wlt.-01xG49X4seDD6yZT",
"moment": "2025-04-05T14:21:40.025Z",
"status": "created"
}
}
]
}
}
],
"page": {
"index": 0,
"limit": 20
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "01930bcf36610d733a3873ddb09a918bca1ee22cd6b45715aa3236fa93010676",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "RPCxKMgoQc2z5t1AyKKdkBsmr9vPbjfynF+9KbeN+ekXglBVgKuZ7sQKfTRyMc/JNJWV+C1O+Pwslz/1VyKVBg==",
"custom": {
"moment": "2025-04-05T14:30:00.100Z"
}
}
]
}
}{
"hash": "b7eb7ccf5ffc126951e13e29a8dcfdaf95db859715d4edfc2d16f59a79d4cd58",
"data": {
"reason": "auth.unauthorized",
"detail": "Invalid token."
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "3acece870c4118bfe4223118e4d2f3cfd5b8947a7093785b66d49aa57fa2890a",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "gnK63DqqWDY/UXvnZHixDKPKS6tfeGHgdARylnPiJLwQGyYxuD97TYbSg2wrzsf/bDrHwQYZaf8Gu5ryYP0UAA==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}{
"hash": "9ec02726b50650add8acfd124c6defeb978a9ac252a5de888f9493ddc701e927",
"data": {
"reason": "auth.forbidden",
"detail": "Request is not authorized"
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "4f8cbdc38d73348de0c31805c783c84a0fecc6be736d7e187004ba68cd00e675",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "P3hRnveehtuobb4AIO56XBmiduvmYJbpdmOHltG/IifBEH7QSWdv/0pqled4SO9x1Ne3oXuWxJy40DzMvx1MBA==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}{
"hash": "bd1e78b47e837376b7994e3e481aa547c110c4d6a1c1d8ecd047cc465edd33bd",
"data": {
"reason": "api.request-timeout",
"detail": "Processing of request on server timed out. Your request may or may not have been processed."
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "cdf5b09c809ec52934cd76ca3b0aa59310049e3cae8b171aee3cf9e0f98bddb2",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "6h1lhq3TOccWrfIdtOa9pkz9pIHVAN9tyXuNaucvLpbspWACog6HpSAdr0FSwGzn0zAKwx8YppGOVjFhfeBLBw==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}{
"hash": "1c084e8dcfb9bb84bc8ea96e9e137b149a34b2bbd85f8e60b4263f5aba980476",
"data": {
"custom": {
"errors": [
{
"instancePath": "/handle",
"schemaPath": "#/properties/handle/pattern",
"keyword": "pattern",
"params": {
"pattern": "^[a-zA-Z0-9_\\-+.]+$"
},
"message": "must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
}
]
},
"reason": "record.schema-invalid",
"detail": "Schema validator error: data.handle must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "7a5febb431719b6f43d7e88e79211308e16ac651b71b339276373fdb4e7c3760",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "2/1zYw4AaIzsIHfOIC6V/CHw6owbjYHt48cwmFOig0ibeT0IbojLmj1RCRi8W00ka0udPa9WsacWDd7ObMY8CA==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}{
"hash": "93a5f4d97a42c2df97f827c58ff7768d02568c15aca931e22b81fa3160ba0df3",
"data": {
"reason": "api.unexpected-error",
"detail": "An unexpected error occurred"
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "efaf5360143b586917d9636779ad6e08571c5b06909a20dd0f5eba4bf3be7eae",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "hERh6Aecj59iR+Fb25OQsHJScOi4t8EiffKSfjlMQdjHMccTnfDlgZFdaJzXzUtpSwy/NHq0l+7ydh3HSWCoAg==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}Query Parameters
page?
Pagination options. Set limit and index to page through results.
filter?
Filter by field values using dot notation (e.g. data.handle=value). Operators like $in and $regex are optional — equality is the default.
Header Parameters
x-ledger?|
The unique identifier of ledger in context for multi tenant requests.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
Create wallet POST
The wallet is created with an empty balance sheet. Balances are managed exclusively through intents — issue claims add balance, transfer claims move it between wallets, and destroy claims remove it. Wallets support routes that forward debits or credits to other wallets, enabling flexible payment topologies. Broadcasts the `wallet-created` signal. Use [effects](/ledger/reference/api/effect) to subscribe.
Get wallet GET
Next Page