Usage

This guide walks through day-to-day operation of a self-hosted SwissKnife instance: signing in, checking your balance, receiving and sending payments over Lightning and on-chain Bitcoin, and automating everything with scoped API keys.

Every operation described here is available both from the Dashboard UI and from the REST API. The full, always-up-to-date endpoint reference (request/response schemas, required permissions, and an interactive playground) lives at api.numeraire.tech/docs. When self-hosting, the same API is served by your own instance (default port 3000 for the all-in-one image), so substitute your instance URL for the examples below.

tip

The /v1/me endpoints are the main access point for an authenticated account. Account settings and API keys are account-scoped, while balances, invoices, payments, contacts, and Bitcoin addresses require an explicit wallet path: /v1/me/wallets/{wallet_id}/....

Signing in

SwissKnife self-hosted is single-tenant by default: on first launch you create one initial Admin account. There is no static admin password in the configuration file; it is set once through the sign-up flow and stored hashed in the database.

First launch (initial setup)

When the dashboard starts, it checks setup status via GET /v1/system/setup, which returns:

• welcome_complete — whether the welcome flow has been completed.
• sign_up_complete — whether the Admin account has been created.

Complete the welcome step (the dashboard calls POST /v1/system/mark-welcome-complete), then create the Admin account by setting a password. Sign-up only collects a password (entered and confirmed); there are no name, email, or profile fields.

# Create the initial Admin account (JWT auth provider only)
curl -X POST https://your-instance:3000/v1/auth/sign-up \
  -H 'Content-Type: application/json' \
  -d '{ "password": "<your-admin-password>" }'
# => { "token": "<jwt>" }

note

Sign-up is only available when SwissKnife is configured with the JWT auth provider. If you use OAuth2 / OIDC, the Admin identity and login are handled by your external OpenID provider via redirect, and you do not create a password here. See the Authentication configuration page.

Subsequent logins

Authenticate with the password you set to obtain a JWT:

curl -X POST https://your-instance:3000/v1/auth/sign-in \
  -H 'Content-Type: application/json' \
  -d '{ "password": "<your-admin-password>" }'
# => { "token": "<jwt>" }

Send the returned token as a Bearer credential on subsequent requests:

curl https://your-instance:3000/v1/me \
  -H 'Authorization: Bearer <jwt>'

The initial local-JWT account is granted all administrative permissions. For programmatic access with independently revocable credentials and no unnecessary admin scopes, use API keys instead.

Checking your balance

Fetch your account, select one of its wallets, then request the balance for that wallet:

• GET /v1/me — your account profile and lightweight wallet list.
• PUT /v1/me — update your account display name.
• GET /v1/me/wallets — wallets owned by your account.
• GET /v1/me/wallets/{wallet_id}/balance — the selected wallet's balance breakdown.

curl https://your-instance:3000/v1/me/wallets \
  -H 'Authorization: Bearer <jwt>'

curl https://your-instance:3000/v1/me/wallets/<wallet-id>/balance \
  -H 'Authorization: Bearer <jwt>'

Wallets embedded in an account include asset metadata and balances, but omit payments, invoices, addresses, contacts, and other related resources. Fetch the selected wallet or one of its child routes by ID when that data is needed.

Native BTC balances are reported in millisatoshis (msat) with these fields:

Field	Meaning
available_msat	Amount available to spend.
reserved_msat	Amount reserved for pending outgoing payments.
received_msat	Total amount received.
sent_msat	Total amount sent (settled outgoing payments).
fees_paid_msat	Total routing/network fees paid.

Account-scoped /v1/me routes require authentication and enforce wallet ownership; they do not consume administrative permission scopes.

The dashboard loads the full account wallet list into its account context. The wallet selector in the header controls every wallet-scoped page and persists active_wallet_id in your account preferences; changing wallets does not infer or silently fall back to the first wallet.

Where to go next

• Payments: receive, send, estimate fees, and manage on-chain addresses.
• Events: subscribe to settlement notifications and handle reconnects.
• Account administration: manage accounts and permissions.
• API keys: connect applications with separately revocable credentials.
• Browse the complete, interactive endpoint reference at api.numeraire.tech/docs.
• Configure liquidity providers and the on-chain wallet in Configuration.
• Review the permission model in Authorization.