Documentation/canton-network-docs/Wallet GatewayUse the Wallet GatewayView on canton-network-docs ↗
canton-network-docs/Wallet GatewayUse the Wallet Gateway

Automate with the User API

The User API is the JSON-RPC 2.0 API behind the User UI. Anything a person can do in the UI — manage sessions, networks, identity providers, wallets, and transactions — you can do programmatically with the same API. Use it to script wallet setup, build a custom wallet UI embedded in your app, or automate operations from a backend. This guide walks through a typical automation flow. For the full method list, authentication rules, and the OpenRPC specification, see the User API reference.
The User API drives your own wallets and setup. It is different from the dApp API, which dApps call through the dApp SDK to connect to a user’s wallet.

​
Before you start

You need:
  • A running Wallet Gateway you can reach (for example http://localhost:3030). See the Quickstart.
  • At least one configured network and identity provider. See Networks & identity providers.
  • A way to obtain a JWT from that identity provider for the user you are automating.
All calls are JSON-RPC 2.0 POST requests to the User API base path (/api/v0/user by default, configurable via server.userPath): 
curl -X POST http://localhost:3030/api/v0/user \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <jwt-token>' \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "<method>", "params": { } }'
Most methods require the Authorization header. Three methods are available without it so a client can bootstrap a connection: addSession(), listNetworks(), and listIdps().
Parameter shapes vary per method. Use the OpenRPC specification as the source of truth for exact request and response fields.

​
Create a session

Start the connection with addSession() (no authentication required), then complete your identity provider’s auth flow to obtain a JWT. Pass that JWT in the Authorization header on every later call. 
curl -X POST http://localhost:3030/api/v0/user \
  -H 'Content-Type: application/json' \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "addSession", "params": { } }'
The Wallet Gateway issues a session tied to the authenticated user. List active sessions with listSessions() and end the current one with removeSession().

​
Discover networks and identity providers

List what the Wallet Gateway offers before creating wallets. Both calls work without authentication. 
# List configured networks
curl -X POST http://localhost:3030/api/v0/user \
  -H 'Content-Type: application/json' \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "listNetworks", "params": { } }'

# List identity providers
curl -X POST http://localhost:3030/api/v0/user \
  -H 'Content-Type: application/json' \
  -d '{ "jsonrpc": "2.0", "id": 3, "method": "listIdps", "params": { } }'
Admins can also manage these at runtime with addNetwork(), removeNetwork(), addIdp(), and removeIdp(). Admin privileges are granted to the user configured as server.admin; see Configure the Wallet Gateway.

​
Create and manage wallets

Create a wallet by choosing a network and a signing provider, then manage the set with the wallet methods. 
# Create a wallet (party) on a network
curl -X POST http://localhost:3030/api/v0/user \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <jwt-token>' \
  -d '{ "jsonrpc": "2.0", "id": 4, "method": "createWallet", "params": { } }'
MethodDescription
createWallet()Create a new wallet (party) on a network.
listWallets()List all wallets for the current user.
setPrimaryWallet()Set the primary wallet dApps default to.
removeWallet()Remove a wallet from the Wallet Gateway.
syncWallets()Sync wallets with the ledger.
isWalletSyncNeeded()Check whether a wallet sync is needed.

​
Sign and execute a transaction

Once a wallet exists, sign and submit transactions with sign() and execute(), then read status with the transaction methods. 
# Sign a prepared transaction
curl -X POST http://localhost:3030/api/v0/user \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <jwt-token>' \
  -d '{ "jsonrpc": "2.0", "id": 5, "method": "sign", "params": { } }'

# Execute a signed transaction
curl -X POST http://localhost:3030/api/v0/user \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <jwt-token>' \
  -d '{ "jsonrpc": "2.0", "id": 6, "method": "execute", "params": { } }'
Read transactions with getTransaction() and listTransactions(). Signing is delegated to the wallet’s signing provider, so the key never leaves that provider.

​
Follow transactions in real time

The dApp API exposes Server-Sent Events for real-time updates (txChanged, accountsChanged, connected, statusChanged). If you are building a custom UI, subscribe to them instead of polling. See Real-time events.

​
End the session

When you are done, end the session: 
curl -X POST http://localhost:3030/api/v0/user \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <jwt-token>' \
  -d '{ "jsonrpc": "2.0", "id": 7, "method": "removeSession", "params": { } }'

​
Next steps

User API reference

Every method, authentication rules, rate limits, and the OpenRPC spec.

Manage wallets

The same operations in the User UI.

Approve & sign transactions

How approval and signing work end to end.

Signing providers

Where each wallet’s keys live and who signs.