canton-network · joel-da · Aug 24, 2026
@@ -44,14 +44,25 @@ For developers **running or configuring** the Wallet Gateway server that mediate
 
 **Contents:**
 
-- [Getting Started](wallet-gateway/getting-started/index.md)
-- [Configuration](wallet-gateway/configuration/index.md)
-- [Automations](wallet-gateway/automations/index.md)
-- [Usage](wallet-gateway/usage/index.md)
-- [APIs](wallet-gateway/apis/index.md)
-- [Signing Providers](wallet-gateway/signing-providers/index.md)
-- [Deployment](wallet-gateway/deployment/index.md)
-- [Troubleshooting](wallet-gateway/troubleshooting/index.md)
+- [Overview](wallet-gateway/index.md)
+- [Quickstart](wallet-gateway/quickstart.md)
+- Set up and operate
+    - [Configure the Wallet Gateway](wallet-gateway/operate/configure.md)
+    - [Networks and identity providers](wallet-gateway/operate/networks-and-identity.md)
+    - [Signing providers](wallet-gateway/operate/signing-providers.md)
+    - [Deploy](wallet-gateway/operate/deploy.md)
+    - [Security checklist](wallet-gateway/operate/security.md)
+    - [Troubleshooting](wallet-gateway/operate/troubleshooting.md)
+- Use the Wallet Gateway
+    - [Party management](wallet-gateway/use/party-management.md)
+    - [Approve and sign transactions](wallet-gateway/use/approve-and-sign.md)
+- Automation
+    - [Automate with the User API](wallet-gateway/automation/automate-with-user-api.md)
+    - [Service account automations](wallet-gateway/automation/service-account-automations.md)
+- Reference
+    - [Configuration reference](wallet-gateway/reference/configuration-reference.md)
+    - [dApp API](wallet-gateway/reference/dapp-api.md)
+    - [User API](wallet-gateway/reference/user-api.md)
 
 **Audience:** Operators and backend developers deploying the Wallet Gateway or integrating it with signing providers and identity systems.
 

@@ -37,14 +37,14 @@ The **dApp API** is a JSON-RPC 2.0 interface specified by **CIP-103**.
 You can call it directly (e.g. over HTTP or SSE) from your frontend or backend.
 In practice, most developers use the **dApp SDK**, which implements the same protocol and adds a simpler API, multi-transport support (HTTP for remote Gateways, `postMessage` for browser-extension wallets), and an EIP-1193–style provider interface via `getConnectedProvider()` after `connect()`.
 The dApp API lets your frontend connect to a wallet, list accounts, prepare and execute transactions, and receive real-time updates; all of this requires a valid session (JWT).
-See [APIs](../wallet-gateway/apis/index.md) and the [dApp SDK](../dapp-sdk/overview.md) documentation.
+See the [dApp API reference](../wallet-gateway/reference/dapp-api.md) and the [dApp SDK](../dapp-sdk/overview.md) documentation.
 
 ## User API and User UI
 
 The **User API** is for users and automation: sessions, networks, identity providers, wallets, and transaction signing.
 The **User UI** (served by the Wallet Gateway) is a web interface that uses the User API so users can log in, create and manage wallets, approve dApp transactions, and change settings.
 For custom integrations or scripts, you can call the User API directly instead of using the User UI.
-See [Usage](../wallet-gateway/usage/index.md) and [APIs](../wallet-gateway/apis/index.md).
+See [Party management](../wallet-gateway/use/party-management.md) and the [User API reference](../wallet-gateway/reference/user-api.md).
 
 ## Discovery and Connection Flow
 
@@ -55,6 +55,6 @@ See [Usage](../wallet-gateway/usage/index.md) and [APIs](../wallet-gateway/apis/
 
 ## Where to Go Next
 
-- **Building a dApp?** → Start with the [dApp SDK Quickstart](../dapp-sdk/quickstart.md), then use the [APIs](../wallet-gateway/apis/index.md) (dApp API) as needed.
-- **Running or configuring the Wallet Gateway?** → Start with [Getting Started](../wallet-gateway/getting-started/index.md), then [Configuration](../wallet-gateway/configuration/index.md), [Signing Providers](../wallet-gateway/signing-providers/index.md), and [APIs](../wallet-gateway/apis/index.md) (User API).
-- **Using the User UI or User API?** → See [Usage](../wallet-gateway/usage/index.md) for typical workflows and when to use which interface.
+- **Building a dApp?** → Start with the [dApp SDK Quickstart](../dapp-sdk/quickstart.md), then use the [dApp API reference](../wallet-gateway/reference/dapp-api.md) as needed.
+- **Running or configuring the Wallet Gateway?** → Start with the [Wallet Gateway Quickstart](../wallet-gateway/quickstart.md), then [Configure the Wallet Gateway](../wallet-gateway/operate/configure.md), [Signing providers](../wallet-gateway/operate/signing-providers.md), and the [User API reference](../wallet-gateway/reference/user-api.md).
+- **Using the User UI or User API?** → See [Party management](../wallet-gateway/use/party-management.md) and [Automate with the User API](../wallet-gateway/automation/automate-with-user-api.md).
@@ -0,0 +1,150 @@
+---
+title: 'Automate with the User API'
+description: 'Drive wallet setup, signing, and transactions from a script or backend using 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](../reference/user-api.md).
+
+> [!NOTE]
+> The User API drives **your own** wallets and setup. It is different from the
+> [dApp API](../reference/dapp-api.md), 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](../quickstart.md).
+- At least one configured network and identity provider. See
+  [Networks & identity providers](../operate/networks-and-identity.md).
+- 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`):
+
+```bash
+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()`.
+
+> [!NOTE]
+> Parameter shapes vary per method. Use the
+> [OpenRPC specification](https://github.com/canton-network/wallet/blob/main/api-specs/openrpc-user-api.json)
+> 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.
+
+```bash
+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.
+
+```bash
+# 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](../operate/configure.md#server).
+
+## Create and manage wallets
+
+Create a wallet by choosing a network and a signing provider, then manage the set with the
+wallet methods.
+
+```bash
+# 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": { } }'
+```
+
+| Method                 | Description                               |
+| ---------------------- | ----------------------------------------- |
+| `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.
+
+```bash
+# 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](../operate/signing-providers.md), 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](../reference/dapp-api.md#real-time-events-sse).
+
+## End the session
+
+When you are done, end the session:
+
+```bash
+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](../reference/user-api.md): Every method, authentication rules, rate limits, and the OpenRPC spec.
+- [Party management](../use/party-management.md): The same operations in the User UI.
+- [Approve & sign transactions](../use/approve-and-sign.md): How approval and signing work end to end.
+- [Signing providers](../operate/signing-providers.md): Where each wallet's keys live and who signs.