Guides

Accept CBTC with Payvol

This guide and its example project are in github.com/cayvox/payvol-examples.

Ask for a CBTC payment with a link or a QR code, let the payer check it before they sign, and match the payment to your invoice on your own ledger. This guide walks through it on DevNet, first in the browser and then in code.

Your first payment in five minutes

You need two DevNet wallets: one to pay from, one to be paid into.

1. Get test CBTC. Open the BitSafe faucet, paste the paying wallet's party ID, and request CBTC. If it arrives as an offer, accept it in that wallet.
2. Ask to be paid. On payvol.xyz/app/request, choose CBTC, enter 0.01, the reference INV-0001, and the receiving wallet's party ID. Press Copy the link.
3. Pay. Open the link, or paste it on payvol.xyz/app/pay. Read the review, press Connect a wallet to pay, choose the paying wallet, and approve the transfer there.
4. Match it. On payvol.xyz/app/match, in the same browser, connect the receiving wallet.

Expected result: a row with INV-0001, marked matched, and the CBTC that moved.

The rest of this guide explains each step, and how to do the same from code.

1. What CBTC is

CBTC is a Bitcoin-backed token on the Canton Network, issued by BitSafe. It is a Canton Token Standard (CIP-0056) instrument, served by the Digital Asset Utility Registry. Payvol treats it like any token-standard instrument: an admin party and an id. BitSafe's documentation, docs.bitsafe.finance, is the authority on CBTC itself.

2. What you need

A party ID looks like name::1220 followed by 64 hexadecimal characters. Copy it whole: a shortened party ID is the most common reason a payment cannot be made.

Wallets, as of 2026-10-19. Payvol hands the transfer to the wallet through PartyLayer.

• Loop has paid a CBTC request through Payvol on DevNet.
• Console and Nightly implement the same transfer call in their PartyLayer adapters, and have not been tried with CBTC.
• Walley received that payment, and Match read it through Walley. Sending from Walley through Payvol is coming soon.

3. Get test CBTC

BitSafe runs a faucet for DevNet and TestNet.

1. Open the faucet with DevNet and CBTC selected.
2. Enter the receiving party ID and request test tokens.
3. If the tokens arrive as an offer, accept it in the wallet. BitSafe notes that the receiving participant must have the DA Utility Registry installed. Both wallets used for this guide, Loop and Walley, received CBTC on DevNet.

Expected result: the wallet shows a CBTC balance. Faucet tokens are not MainNet assets.

4. Read CBTC's identity from the registry

Never type CBTC's admin party, id or decimals into your code. Read them from the registry, refresh them every few minutes, and warn when they change. BitSafe states that the admin and id can change with upgrades and that nothing announces it (Instrument ID Management).

The example project does this for you. Set it to DevNet first, so the requests it builds match the app:

cd examples/cbtc
npm install && npm run build
cp .env.example .env
export NETWORK=devnet           # or set NETWORK=devnet in .env
npm run refresh-metadata

Expected result: JSON with "network": "devnet", the DevNet registry, CBTC's admin party, "id": "CBTC", "decimals": 10 and "source": "registry".

The identity per network, as BitSafe publishes it and as the registry answered on 2026-10-18:

The instrument id is CBTC on all three. The metadata lives at {registry}/api/token-standard/v0/registrars/{admin}/registry/metadata/v1/instruments.

5. Create a payment request

A Payvol request is a canton: URI. The same bytes can be a link, a QR code or an NFC tag.

In the browser. On payvol.xyz/app/request, choose CBTC. The page reads CBTC's decimals from the registry and refuses an amount with more.

In code.

npm run create-request -- \
  --recipient payvol-demo-recipient::1220abababababababababababababababababababababababababababababababab \
  --amount 0.0100000000 --expiry 2027-01-01T00:00:00Z --reference INV-0001 --qr

Expected result: JSON with "network": "devnet", the uri, a web+canton: link and the request's digest, then a QR code. Replace the placeholder recipient with the real party ID. An amount with more than 10 decimal places is refused, never rounded: a rounded amount would be a different request.

6. Verify the request

Anyone can check a request before paying it. Verification reads it the way a wallet would, and checks it against what the registry says CBTC is on this network.

In the browser. Paste it on payvol.xyz/app/verify.

In code.

npm run verify-request -- '<the canton: URI from step 5>'

Expected result: "valid": true and "warnings": []. Read the warnings: a request for something that calls itself CBTC under another party is valid as a request and comes back with an ADMIN_NOT_CBTC_REGISTRAR warning. Keep the single quotes, because the URI contains ? and &. The same URI read with NETWORK=mainnet is refused with NOT_THIS_NETWORK, because each network's CBTC has its own registrar.

7. Pay

With a wallet

Paste the request on payvol.xyz/app/pay. The page shows what signing would do before any wallet is involved: who is paid, the asset, the exact amount, the reference and the deadline. The name in the request is the requester's own words. Payvol marks it name not verified: check the party ID, not the name.

Press Connect a wallet to pay, choose your wallet, and approve the transfer in it. The wallet builds the transfer with the registry and shows it to you again. Payvol never sees your key.

Expected result: Pay reads the transfer back and says Paid. when it completed, or Offered, and nothing has moved yet. when it is waiting for the payee to accept. On this path, the request's reference reaches the ledger as the Token Standard's reason, and nothing else from Payvol does: the PartyLayer adapters for Console, Loop and Nightly accept a memo and no other metadata.

With the SDK, on your own participant

npm run pay -- '<the canton: URI>'

pay refuses a request this network's CBTC cannot pay. It then picks holdings, asks the registry for the transfer factory, prints the transfer command it will submit, and submits only after you type yes. For an external party, your participant prepares the transaction and pay signs the hash it returns without decoding it, so this path trusts your own participant to prepare what you reviewed.

Expected result: an updateId. Keep it: the payee needs it in step 8. The transfer carries three values: splice.lfdecentralizedtrust.org/reason (your reference), payvol.xyz/request-digest and payvol.xyz/profile. Anyone who can read the transfer can read them.

8. See the payment and match it to the invoice

What the payee sees depends on how the transfer ended.

In the browser. On payvol.xyz/app/match, connect the receiving wallet in the browser that issued the request. Match reads your own party's view of the ledger through the wallet and marks each payment that carries a reference this browser issued.

Expected result: INV-0001, marked matched. Open the row to see what moved, by holding and owner.

In code. For a payment that arrived as an offer, the example records it on your own participant with @payvol/core:

npm run instructions                                         # the open offers you can see
npm run resolve -- <instructionId> accept                    # prints the accept updateId
npm run trust-from-updates -- <offerUpdateId> <acceptUpdateId>
npm run observe -- '<the canton: URI>' <offerUpdateId> <acceptUpdateId>

<offerUpdateId> is the updateId the payer's pay printed in step 7. <acceptUpdateId> is the one resolve printed. trust-from-updates needs only one offer and its acceptance, once.

Expected result: the outcome's lifecycle, settled, and four checks against the request: the digest, the receiver, the instrument, and whether the amount covers it.

9. Move to MainNet

• Use MainNet's identity, from the registry. The admin party differs on each network; set NETWORK=mainnet and let the example read it. Never mix the networks: a TestNet admin in a MainNet request is a different instrument, and verify-request refuses it.
• Real CBTC comes from real Bitcoin. There is no faucet. Most payers will hold CBTC they received by transfer. Minting it against BTC needs a Minter credential from BitSafe, as Mint CBTC describes.
• The app at payvol.xyz asks wallets for DevNet only today. On MainNet, use the code path.

10. Troubleshooting

Sources