Wallet API
This surface is for a non-custodial web3 wallet that lets its users accept and pay for Bitcoin purchases at a merchant's point of sale. The wallet holds the keys; GoBTC Pay builds the transactions that the wallet signs.
A typical integration is four steps: authenticate the user with their wallet key, register their multisig wallet, read balances, then pay at a POS by scanning a QR and signing the transaction.
- Authentication: sign a server-issued challenge with the wallet's private key, then exchange the signature for a Bearer JWT (
Authorization: Bearer <accessToken>). - Operation groups: Authentication, Wallet (register, address, balances), Payments (get, list, build, settle), Multisig Withdrawal, and Self-Custody Wallet.
The integration, end to end
Authenticate the user
Request a challenge, sign it with the wallet's private key, and exchange the signature for an access token. Send the token as Authorization: Bearer <accessToken> on every subsequent call.
Register the multisig wallet
Call Register wallet with the user's public key. GoBTC Pay provisions the multisig wallet that all payments are spent from and returns its address. Call this once, after generating the key pair.
Read balances
Get balances returns the wallet's balances broken down by state, all in satoshis: on-chain (confirmed and unconfirmed), signed, locked, pending change, and the spendable leftBalance and totalBalance.
An incoming multisig UTXO becomes spendable only after it is confirmed on the Bitcoin main chain.
Pay at a point of sale
Call Get payment with the payment id from the QR code and show the user the amount, merchant, and expiry. Call Build payment transaction to get the unsigned psbtBase64, have the user sign it, then submit it via Settle payment.
The payment becomes paid within moments (see Payment Lifecycle); settlement follows in a later batch.
The connecting wallet earns 0.1% on every transaction it initiates. See What it costs, and who gets paid.