Skip to content

index.md

Latest commit

 

History

History
133 lines (98 loc) · 6.28 KB

index.md

File metadata and controls

133 lines (98 loc) · 6.28 KB
Raw

APIs

The Wallet Gateway exposes two JSON-RPC 2.0 APIs: one for dApps interactions and one for user interactions. Both APIs use the same base URL but different paths.

API Endpoints

  • dApp API: /api/v0/dapp - Used by decentralized applications to interact with wallets and submit transactions
  • User API: /api/v0/user - Used by users to manage wallets, networks, and signing providers

Both APIs follow the JSON-RPC 2.0 specification and use JWT-based authentication for secure access.

dApp API Reference

The dApp API enables decentralized applications to connect to wallets, query ledger state, prepare transactions, and submit commands. This API is designed for programmatic access from web or mobile applications.

Authentication:

The dApp API requires a valid JWT token in the Authorization header:

Authorization: Bearer <jwt-token>

Full API Specification:

The complete OpenRPC specification is available at openrpc-dapp-api.json.

User API Reference

The User API enables users to manage their wallets, configure networks, manage identity providers, create parties, and interact with their wallet through the web UI.

Methods:

Category Method Description
Sessions addSession() Create a new session (unauthenticated, used for initial connection)
removeSession() End the current session
listSessions() List sessions for the current user
Networks listNetworks() List configured networks (public metadata only, no auth secrets)
getNetwork() Get full network configuration including auth (admin only)
selfSignedAccessToken() Mint a self-signed JWT for login (unauthenticated)
addNetwork() Add a new network configuration
removeNetwork() Remove a network configuration
Identity Providers listIdps() List all identity providers
addIdp() Add a new identity provider
removeIdp() Remove an identity provider
Wallets createWallet() Create a new wallet (party) on a network
listWallets() List all wallets for the current user
setPrimaryWallet() Set the primary wallet
removeWallet() Remove a wallet
syncWallets() Sync wallets with the ledger
isWalletSyncNeeded() Check if wallet sync is needed
Transactions sign() Sign a transaction
execute() Execute a signed transaction
getTransaction() Get a transaction by ID
listTransactions() List transactions

Authentication:

Most User API methods require authentication via JWT token. However, the following methods are available without authentication:

  • addSession()
  • listNetworks()
  • listIdps()
  • selfSignedAccessToken()

Full API Specification:

The complete OpenRPC specification is available at openrpc-user-api.json.

Server-Sent Events (SSE) Support

The dApp API supports Server-Sent Events (SSE) for real-time notifications. Connect to the /events path relative to the dApp API base URL (e.g. /api/v0/dapp/events). Authenticate by passing the JWT token as the token query parameter (the Authorization: Bearer header is also supported):

const eventsUrl = new URL('events', dappApiUrl + '/')
eventsUrl.searchParams.set('token', jwtToken)
const eventSource = new EventSource(eventsUrl.toString())

eventSource.addEventListener('accountsChanged', (e) => {
    /* ... */
})
eventSource.addEventListener('statusChanged', (e) => {
    /* ... */
})
eventSource.addEventListener('connected', (e) => {
    /* ... */
})
eventSource.addEventListener('txChanged', (e) => {
    /* ... */
})

SSE connections receive real-time updates about:

  • Transaction status changes (txChanged)
  • Account changes (accountsChanged)
  • Session/connection state (connected, statusChanged)

Rate Limiting

API requests are rate-limited to prevent abuse. The default limits can be configured in the server configuration. Rate limit headers are included in responses:

  • X-RateLimit-Limit - Maximum number of requests per window
  • X-RateLimit-Remaining - Remaining requests in current window
  • X-RateLimit-Reset - Time when the rate limit resets

CORS Configuration

Cross-Origin Resource Sharing (CORS) is configured via the allowedOrigins setting in the server configuration. By default, all origins are allowed (['*']), but for production deployments, you should restrict this to known dApp origins.

Example Configuration:

{
    "server": {
        "allowedOrigins": [
            "https://my-dapp.example.com",
            "https://another-dapp.example.com"
        ]
    }
}

Alternatively, you can allow all origins by setting allowedOrigins to "*".

{
    "server": {
        "allowedOrigins": ["*"]
    }
}