API Reference

Wallets

Ledger accounts identified by a handle (e.g. `svgs:10000001@bancorojo.com.co`), typed by schema and optionally bound to an external bank account via a bridge.

List wallets

GET
/wallets

Authorization

BearerAuth LedgerHeader
AuthorizationBearer <token>

Access token obtained from POST /oauth/token

In: header

x-ledger<token>

Handle of the target ledger (e.g. demo-co)

In: header

Query Parameters

limit?integer

Maximum records to return

Default25
Rangevalue <= 100
offset?integer

Records to skip

Default0
filter[data.schema]?string

Filter by schema handle

filter[data.custom.country]?string

Response Body

application/json

application/json

curl -X GET "https://demo-co.ldg-stg.one/api/v2/wallets?filter%5Bdata.schema%5D=banks&filter%5Bdata.custom.country%5D=co"
{
  "data": [
    {
      "handle": "svgs:10000001@bancorojo.com.co",
      "schema": "banks",
      "custom": {
        "name": "Banco Rojo",
        "country": "co"
      }
    },
    {
      "handle": "svgs:20000001@bancoamarillo.com.co",
      "schema": "banks",
      "custom": {
        "name": "Banco Amarillo",
        "country": "co"
      }
    },
    {
      "handle": "ach@bancoazul.com.co",
      "schema": "network",
      "custom": {
        "name": "Banco Azul ACH",
        "country": "co"
      }
    },
    {
      "handle": "main@comercio-ejemplo.com.co",
      "schema": "merchant",
      "custom": {
        "name": "Comercio Ejemplo SAS",
        "country": "co"
      }
    },
    {
      "handle": "treasury@hub.co",
      "schema": "treasury",
      "custom": {
        "name": "Hub Treasury",
        "country": "co"
      }
    },
    {
      "handle": "fees@hub.co",
      "schema": "fees",
      "custom": {
        "name": "Hub Fees",
        "country": "co"
      }
    }
  ],
  "meta": {
    "total": 6,
    "limit": 25,
    "offset": 0
  }
}
{
  "error": {
    "code": "unauthorized",
    "message": "Bearer token is missing or expired"
  }
}

Create wallet

POST
/wallets

Authorization

BearerAuth LedgerHeader
AuthorizationBearer <token>

Access token obtained from POST /oauth/token

In: header

x-ledger<token>

Handle of the target ledger (e.g. demo-co)

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://demo-co.ldg-stg.one/api/v2/wallets" \  -H "Content-Type: application/json" \  -d '{    "data": {      "handle": "svgs:10000001@bancorojo.com.co",      "schema": "banks",      "custom": {        "name": "Banco Rojo",        "country": "co",        "code": "1099",        "scheme": "nit",        "number": "890100001"      },      "access": [        {          "action": "any",          "signer": {            "$circle": "owner"          }        },        {          "action": {            "$in": [              "read",              "query"            ]          },          "bearer": {            "$signer": {              "$circle": "services"            }          }        }      ]    },    "hash": "a3f5d9b1c2e4f0a8...",    "proofs": [      {        "method": "ed25519-v2",        "public": "MCowBQYDK2VdAyEAabc123...",        "digest": "a3f5d9b1c2e4f0a8...",        "result": "MEQCIB3xdef..."      }    ]  }'
{
  "data": {
    "handle": "svgs:10000001@bancorojo.com.co",
    "schema": "banks",
    "custom": {
      "name": "Banco Rojo",
      "country": "co",
      "code": "1099",
      "scheme": "nit",
      "number": "890100001"
    }
  },
  "meta": {
    "created": "2026-06-08T10:00:00.000Z",
    "updated": "2026-06-08T10:00:00.000Z"
  }
}
{
  "error": {
    "code": "schema-validation-failed",
    "message": "Required field 'schema' is missing from data"
  }
}
{
  "error": {
    "code": "unauthorized",
    "message": "Bearer token is missing or expired"
  }
}
{
  "error": {
    "code": "handle-conflict",
    "message": "A record with this handle already exists"
  }
}

Get wallet

GET
/wallets/{handle}

Authorization

BearerAuth LedgerHeader
AuthorizationBearer <token>

Access token obtained from POST /oauth/token

In: header

x-ledger<token>

Handle of the target ledger (e.g. demo-co)

In: header

Path Parameters

handle*string

Wallet handle (URL-encoded if contains special characters)

Response Body

application/json

application/json

curl -X GET "https://demo-co.ldg-stg.one/api/v2/wallets/svgs%3A10000001%40bancorojo.com.co"

{
  "data": {
    "handle": "svgs:10000001@bancorojo.com.co",
    "schema": "banks",
    "custom": {
      "name": "Banco Rojo",
      "country": "co",
      "code": "1099",
      "scheme": "nit",
      "number": "890100001"
    }
  },
  "meta": {
    "created": "2026-06-08T10:00:00.000Z",
    "updated": "2026-06-08T10:00:00.000Z"
  }
}

{
  "error": {
    "code": "not-found",
    "message": "Wallet not found"
  }
}

Get wallet balances

GET
/wallets/{handle}/balances

Authorization

BearerAuth LedgerHeader
AuthorizationBearer <token>

Access token obtained from POST /oauth/token

In: header

x-ledger<token>

Handle of the target ledger (e.g. demo-co)

In: header

Path Parameters

handle*string

Wallet handle (URL-encoded if contains special characters)

Response Body

application/json

application/json

curl -X GET "https://demo-co.ldg-stg.one/api/v2/wallets/svgs%3A10000001%40bancorojo.com.co/balances"
{
  "data": [
    {
      "symbol": "cop",
      "amount": "18500000",
      "available": "18500000"
    }
  ]
}
{
  "error": {
    "code": "not-found",
    "message": "Wallet not found"
  }
}

Auth

OAuth 2.0 client-credentials token exchange — obtain a Bearer token to authenticate all subsequent requests.

Intents

Signed payment instructions composed of one or more claims (`transfer`, `issue`, `destroy`, `limit`) that progress through states — `pending` → `prepared` → `committed` → `completed` or `rejected`.

On this page

No Headings