The Problem We Solve

Bitcoin is the most liquid, most decentralized digital asset — but its value largely lives outside institutional blockchain networks. Canton is a privacy-preserving network built for institutional-grade applications — but moving value in and out of it has traditionally required custodial on-ramps, market accounts, and waiting.

Tritemius is the bridge between the two: a direct, near-instant, programmatic exchange where a Lightning payment on one side becomes a Canton asset on the other — and vice versa.

Why the Bitcoin Lightning Network

• Instant, final settlement — payments confirm in seconds, not blocks.
• Negligible fees — routing costs are a fraction of on-chain fees, so even small swaps make sense.
• HOLD invoices — Lightning lets us accept a payment without settling it. Your payment is only settled after the Canton asset has been delivered; if delivery fails, the payment is released back to you. No trust required in the happy path.
• Universal reach — any Lightning wallet, Lightning Address or LNURL works.

Why the Canton Network

• Privacy-preserving by design — transactions are visible only to their participants, not to the whole network.
• Institutional-grade infrastructure — the Global Synchronizer connects regulated financial actors on shared rails.
• A real asset ecosystem — Canton Coin powers the network, and token-standard assets like CBTC and USDCx bring Bitcoin and dollar liquidity on-chain.
• Programmable settlement — token-standard transfers with memos let the exchange match and settle swaps automatically.

Public Swap API

Base URL: https://app.tritemius.net

• No authentication — all swap endpoints are public.
• Amounts: CC / CBTC / USDCx are decimal strings; sats are integers.
• The exchange's Canton party ID is returned by GET /api/exchange/info — always read it from there, never hardcode it.

Supported swap pairs

Limits

These values can change — read them live from the discovery endpoints below; they are the source of truth.

1 · Discovery Endpoints

Read these first — limits and the exchange party ID come from here.

GET/api/exchange/info

GET/api/exchange/rates — CC pricing

GET/api/exchange/swap/rates/cbtc

CBTC is sat-pegged: 1 CBTC = 100,000,000 sats.

GET/api/exchange/swap/rates/usdcx

Reserve liquidity — check before large swaps

CC liquidity is not exposed directly — a BTC→CC swap creation fails with 503 if the CC reserve can't cover it.

GET/api/exchange/quote — CC price preview

2 · Lightning → Canton Asset

Identical flow for CC, CBTC and USDCx — only the endpoint and the receive field differ. Two steps: create the swap → pay the HOLD invoice. The exchange delivers the asset to your Canton party as soon as the Lightning payment is held; the invoice is only settled after successful delivery. If delivery fails, your payment is released back.

2.1 · Create

Response 200 (CC example — CBTC has cbtcAmount, USDCx has usdcxAmount instead of ccAmount):

Creation errors: 400 (bad sats/party), 503 insufficient asset reserve or insufficient inbound Lightning capacity — retry later or with a smaller amount.

2.2 · Pay the invoice, poll until complete

Pay paymentRequest from any Lightning wallet before expiresAt, then poll GET /api/exchange/swap/<id>.

State machine: pending → htlc_received (payment held) → cc_sending / cbtc_sending / usdcx_sending → complete. Not paid in time → expired. Delivery failure → failed with errorMsg.

3 · Canton Asset → Lightning

Flow: create the swap (registering your Lightning destination) → send the asset to the exchange party with the swap id as the memo. The exchange detects the payment by memo and pays your Lightning invoice.

3.1 · Create

receiverLnInvoice accepts a BOLT11 invoice, a Lightning Address (name@domain.com) or an LNURL. For BOLT11: its amount must match the payout within ~0.25% (get a quote first), it must not expire within 2 minutes, and an invoice can be used for only one swap.

Response 200 (CBTC example — CC/USDCx analogous):

Creation errors: 400 (bad amount, invalid/expired/mismatched/reused invoice, unresolvable Lightning address), 503 insufficient outbound Lightning capacity.

3.2 · Pay the Canton side — the memo is mandatory

• CC: a token-standard transfer with description = the swap id (bare id, nothing else). Amount must be within 1% of the swap's ccAmount.
• CBTC / USDCx: a token-standard TransferOffer with the memo/reason field = the swap id. The exchange auto-accepts the offer matching the id.

3.3 · Poll until complete

GET /api/exchange/swap/<id>: pending_cc / pending_cbtc / pending_usdcx → (asset received) paying → complete. Special states:

• verifying — the Lightning payment errored ambiguously; the exchange re-checks before deciding. No action needed.
• failed + errorMsg — for CC swaps the CC is auto-refunded to the sending party when the Lightning payment definitively failed; CBTC/USDCx refunds are handled manually. The asset is never kept without a payout.
• expired — you didn't send the asset in time; nothing was taken.

4 · Status & History

Swap objects are the public shape shown above. errorMsg appears on failures and is safe to show to users.

5 · Integration Notes

1. Always quote first and create the swap immediately — rates move; the swap locks its amounts at creation, valid for 300 s (5 minutes). A payment arriving after expiry fails safely and bounces back.
2. Hold-invoice semantics (LN→asset): the user's Lightning payment shows "in flight" until the asset is delivered, then settles. This is normal — don't treat a held payment as stuck before the swap reaches a final state.
3. The memo rule (asset→LN): bare swap id, exact field (description for CC, offer memo/reason for CBTC/USDCx), within the 300 s window, amount within tolerance.
4. Poll every ~3 s; final states are complete, expired, failed.
5. Liquidity 503s are transient — inbound/outbound Lightning capacity and asset reserves fluctuate. Back off and retry, or reduce the amount.
6. Rate limits on swap creation: per client IP, a burst of 5 creations with a sustained rate of 3/minute → 429 with a Retry-After header. A global busy-guard can answer 503 ("Exchange is busy") when too many unpaid swaps are open. Quotes, rates and status polling are NOT rate-limited — poll freely. Create swaps only on explicit user action and you will never hit either.
7. Lightning invoices the exchange issues carry the memo CC-swap:<swap-id>.
8. Rate/limit values on this page are illustrative — the discovery endpoints are the source of truth.

6 · Displaying the Lightning Invoice

Practical notes from our own UI for rendering paymentRequest:

• UPPERCASE the invoice before QR-encoding. BOLT11 is case-insensitive and uppercase enables the QR alphanumeric mode — a noticeably smaller, easier-to-scan code.
• Low error correction is fine — level L (or M). High EC only adds density on long invoices.
• Give it room: ≥200×200 px with a quiet zone (margin ≥4 modules) on a white background — even in dark UIs, render the QR itself on white. Prefer generating client-side.
• Always pair the QR with a copy button and a tap-to-open link (lightning: URI) — mobile users often have the wallet on the same device and can't scan their own screen. Put the lightning: prefix only in the link, not inside the QR data.
• Show a countdown to expiresAt and refresh the view when it hits zero; on expiry offer one-click "get a new quote".
• Don't regenerate the QR on every poll tick — render once per invoice.
• Show the amount in both units (sats + asset amount) near the QR.