> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canton.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Automate with the User API

> 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](/integrations/wallet-gateway/reference/user-api).

<Note>
  The User API drives **your own** wallets and setup. It is different from the
  [dApp API](/integrations/wallet-gateway/reference/dapp-api), which dApps call through the dApp
  SDK to connect to a user's wallet.
</Note>

## Before you start

You need:

* A running Wallet Gateway you can reach (for example `http://localhost:3030`). See the
  [Quickstart](/integrations/wallet-gateway/quickstart).
* At least one configured network and identity provider. See
  [Networks & identity providers](/integrations/wallet-gateway/operate/networks-and-identity).
* 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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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-gateway/blob/main/api-specs/openrpc-user-api.json)
  as the source of truth for exact request and response fields.
</Note>

## 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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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](/integrations/wallet-gateway/operate/configure#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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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](/integrations/wallet-gateway/operate/signing-providers), 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](/integrations/wallet-gateway/reference/dapp-api#real-time-events-sse).

## End the session

When you are done, end the session:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

<CardGroup cols={2}>
  <Card title="User API reference" href="/integrations/wallet-gateway/reference/user-api">
    Every method, authentication rules, rate limits, and the OpenRPC spec.
  </Card>

  <Card title="Manage wallets" href="/integrations/wallet-gateway/use/manage-wallets">
    The same operations in the User UI.
  </Card>

  <Card title="Approve & sign transactions" href="/integrations/wallet-gateway/use/approve-and-sign">
    How approval and signing work end to end.
  </Card>

  <Card title="Signing providers" href="/integrations/wallet-gateway/operate/signing-providers">
    Where each wallet's keys live and who signs.
  </Card>
</CardGroup>