Wallet

Wallet lifecycle and read access: register a device key, resolve the multisig address, and read balances and UTXOs.

Register wallet

POSThttps://api.gobtcpay.com/public/api/v1.2/instant/wallet/register

Registers the user's wallet public key and provisions their multisig wallet, the user's main wallet that all payments are spent from. Call this once after generating the key pair; returns the multisig address.

Authorization: walletAuth

Body required

application/json

userPubKeyHexstringrequired

Public key of the user's Bitcoin wallet, compressed secp256k1 key, hex (33 bytes). Becomes a signer of the new multisig wallet.

Example:02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /instant/wallet/register

cURL

curl -X POST "$BASE_URL/instant/wallet/register" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "userPubKeyHex": "02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
      "serverPubKeyHex": "02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc"
    }
  }
}

Get wallet address

POSThttps://api.gobtcpay.com/public/api/v1.2/instant/wallet/get

Returns the authenticated user's multisig wallet address.

Authorization: walletAuth

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /instant/wallet/get

cURL

curl -X POST "$BASE_URL/instant/wallet/get" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
      "serverPubKeyHex": "02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc"
    }
  }
}

Get balances

POSThttps://api.gobtcpay.com/public/api/v1.2/instant/wallet/get-balances

Returns the wallet's balances broken down by state, on-chain (confirmed / unconfirmed), signed, locked, pending change, the spendable leftBalance and totalBalance, all in satoshis. leftBalance is confirmedOnChainBalance - lockedBalance - signedBalance (floored at 0) and the reservation buckets never overlap; totalBalance additionally includes pendingChangeBalance, our own change from an already broadcast but still unconfirmed transaction, which is not spendable yet. leftBalanceInUsd / leftBalanceInCurrency give the fiat equivalent (null when a rate is unavailable). Pass currency to choose the fiat conversion.

Authorization: walletAuth

Body required

application/json

currencystring

Optional fiat currency for the converted balance fields (e.g. USD).

Example:USD

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /instant/wallet/get-balances

cURL

curl -X POST "$BASE_URL/instant/wallet/get-balances" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "currency": "USD"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "onChainBalance": "string",
      "confirmedOnChainBalance": "string",
      "unconfirmedOnChainBalance": "string",
      "signedBalance": "string",
      "lockedBalance": "string",
      "pendingChangeBalance": "string",
      "leftBalance": "string",
      "totalBalance": "string",
      "leftBalanceInUsd": 50000,
      "leftBalanceInCurrency": 50000
    }
  }
}