{ "openapi": "3.1.0", "info": { "title": "GoBTC Pay Wallet API", "version": "v1.2", "x-logo": { "url": "https://upload.wikimedia.org/wikipedia/commons/6/62/GoMining_Logo_%28Black%29.png" }, "description": "# GoBTC Pay — Wallet API\n\nThis API lets a non-custodial **web3 wallet** integrate GoBTC Pay so its\nusers can accept and pay for Bitcoin purchases at a merchant's point of\nsale. The wallet holds the keys; GoBTC Pay builds the transactions the\nwallet signs. A typical integration follows four steps:\n\n1. **[Authenticate](#authentication)** the user with their wallet key.\n2. **[Register the wallet](#wallet-setup)** to provision their multisig wallet.\n3. **[Read balances](#balances-and-addresses)** to show funds and the wallet address.\n4. **[Pay at a POS](#paying-at-a-pos)** by scanning a QR code and signing the payment.\n\nEvery authenticated request carries a short-lived **Bearer JWT** obtained\nfrom the challenge–signature flow below.\n\n## Authentication\n\nThe wallet proves control of its key by signing a server-issued challenge,\nthen exchanges the signature for an access / refresh token pair:\n\n1. Call **Get sign-in challenge** with the user's public key. The response\n contains the data to sign (`messageToSign`).\n2. Sign that data with the corresponding **private key**.\n3. Submit the signature to **Get access tokens** to receive an `accessToken`\n and a `refreshToken`.\n4. Send every authenticated request with `Authorization: Bearer `.\n5. When the access token expires, get a fresh pair via **Refresh access tokens**.\n\n```mermaid\nsequenceDiagram\n participant W as Wallet app\n participant G as Gateway\n W->>G: Get sign-in challenge (public key)\n G-->>W: messageToSign\n W->>W: sign messageToSign with private key\n W->>G: Get access tokens (signature)\n G-->>W: accessToken + refreshToken\n W->>G: API call (Authorization: Bearer accessToken)\n W->>G: Refresh access tokens (refreshToken)\n G-->>W: new accessToken + refreshToken\n```\n\n## Wallet setup\n\nOnce authenticated, call **Register wallet** with the user's public key.\nGoBTC Pay provisions and returns the user's **multisig wallet** — this is\nthe user's main wallet, and every payment is spent from it. Call this once,\nafter generating the key pair.\n\n## Balances and addresses\n\n- **Get balances** — the wallet's balances broken down by state (on-chain,\n signed, locked, spendable), with optional fiat conversion.\n- **Get wallet address** — the user's multisig wallet address.\n\n## Paying at a POS\n\nWhen the user scans the QR code shown on a merchant's POS terminal:\n\n1. Call **Get payment** with the payment id from the QR code, and show the\n user the payment details (amount, merchant, expiry).\n2. Call **Build payment transaction** with that payment. The response\n returns a `psbtBase64` — the unsigned transaction. Present it so the user\n can review what they are signing.\n3. The user signs the PSBT with their key. Submit the signed transaction via\n **Settle payment** to complete the payment.\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant W as Wallet app\n participant G as Gateway\n participant P as POS terminal\n P-->>U: show payment QR\n U->>W: scan QR (paymentId)\n W->>G: Get payment (paymentId)\n G-->>W: payment details\n W->>U: show amount & merchant\n W->>G: Build payment transaction (paymentId)\n G-->>W: psbtBase64\n W->>U: review & sign\n W->>G: Settle payment (signed PSBT)\n G-->>W: paymentTxId\n```\n\n---\n\nThis is the **Wallet** surface of the GoBTC Pay API. Backwards compatibility is preserved across published versions.\n\nFound an error in the docs? Email [support@gomining.com](mailto:support@gomining.com)." }, "components": { "securitySchemes": { "merchantAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer `. Refresh it via `/merchant/auth/refresh` when it expires." }, "walletAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Wallet access token obtained from `/instant/auth/get-jwt` via the signature challenge flow. Send it as `Authorization: Bearer `. Refresh it via `/instant/auth/refresh-jwt` when it expires." } } }, "servers": [ { "url": "https://api.gobtcpay.com/public/api/v1.2" } ], "paths": { "/instant/auth/get-data-to-sign": { "post": { "security": [], "summary": "Get sign-in challenge", "description": "Starts the authentication challenge. Returns a one-time `messageToSign` and a `challengeId` bound to the supplied public key (valid until `expiresAt`, ~5 min). Sign `messageToSign` verbatim with the corresponding private key using Bitcoin message signing (secp256k1 ECDSA), then exchange it for tokens via **Get access tokens**.", "tags": [ "Authentication" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userPubKeyHex": { "type": "string", "description": "Public key of the user's Bitcoin wallet to authenticate — compressed secp256k1 key, hex (33 bytes / 66 chars).", "example": "02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc" } }, "required": [ "userPubKeyHex" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "challengeId": { "type": "string", "description": "Unique id of this challenge. Pass it back to **Get access tokens** together with your signature.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "messageToSign": { "type": "string", "description": "Message to sign verbatim with the wallet private key (Bitcoin message signing, secp256k1).", "example": "instant-go login;pubkey=02a1633c;nonce=Zm9vYmFyYmF6;issuedAt=2026-06-11T10:00:00.000Z;expiresAt=2026-06-11T10:05:00.000Z" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "When the challenge expires, Unix timestamp (seconds). Sign and submit before this time (~5 min).", "example": 1718012345 } }, "required": [ "challengeId", "messageToSign", "expiresAt" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"$BASE_URL/instant/auth/get-data-to-sign\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"userPubKeyHex\": \"02ab…\"\n}'" }, { "lang": "javascript", "label": "JavaScript", "source": "const res = await fetch(`${BASE_URL}/instant/auth/get-data-to-sign`, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({\n \"userPubKeyHex\": \"02ab…\"\n }),\n});\n\nconst { result } = await res.json();" } ] } }, "/instant/auth/get-jwt": { "post": { "security": [], "summary": "Get access tokens", "description": "Completes the authentication challenge. Submit the `challengeId` from **Get sign-in challenge** together with the hex-encoded 64-byte compact `signature` of `messageToSign`. Returns a short-lived `accessToken` (send it as `Authorization: Bearer `) and a long-lived `refreshToken`.", "tags": [ "Authentication" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string", "description": "The `challengeId` returned by **Get sign-in challenge** (`/instant/auth/get-data-to-sign`).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "signature": { "type": "string", "description": "Hex-encoded 64-byte compact signature of the `messageToSign` from **Get sign-in challenge**.", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" } }, "required": [ "challengeId", "signature" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Short-lived JWT access token. Send it as `Authorization: Bearer ` on authenticated requests.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "refreshToken": { "type": "string", "description": "Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" } }, "required": [ "accessToken", "refreshToken" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"$BASE_URL/instant/auth/get-jwt\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"challengeId\": \"chg_…\",\n \"signature\": \"3045…\"\n}'" }, { "lang": "javascript", "label": "JavaScript", "source": "const res = await fetch(`${BASE_URL}/instant/auth/get-jwt`, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({\n \"challengeId\": \"chg_…\",\n \"signature\": \"3045…\"\n }),\n});\n\nconst { result } = await res.json();" } ] } }, "/instant/auth/refresh-jwt": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Refresh access tokens", "description": "Exchanges a valid refresh token for a fresh `accessToken` / `refreshToken` pair without repeating the signing challenge. Send the refresh token as `Authorization: Bearer ` with an empty body.", "tags": [ "Authentication" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Short-lived JWT access token. Send it as `Authorization: Bearer ` on authenticated requests.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "refreshToken": { "type": "string", "description": "Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" } }, "required": [ "accessToken", "refreshToken" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/instant/wallet/register": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Register wallet", "description": "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`.", "tags": [ "Wallet" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userPubKeyHex": { "type": "string", "description": "Public key of the user's Bitcoin wallet — compressed secp256k1 key, hex (33 bytes). Becomes a signer of the new multisig wallet.", "example": "02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc" } }, "required": [ "userPubKeyHex" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "address": { "type": "string", "description": "The user's newly provisioned multisig wallet address.", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "serverPubKeyHex": { "type": "string", "example": "02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc" } }, "required": [ "address", "serverPubKeyHex" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"$BASE_URL/instant/wallet/register\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"userPubKeyHex\": \"02ab…\"\n}'" }, { "lang": "javascript", "label": "JavaScript", "source": "const res = await fetch(`${BASE_URL}/instant/wallet/register`, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({\n \"userPubKeyHex\": \"02ab…\"\n }),\n});\n\nconst { result } = await res.json();" } ] } }, "/instant/wallet/get": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Get wallet address", "description": "Returns the authenticated user's multisig wallet `address`.", "tags": [ "Wallet" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "address": { "type": "string", "description": "The user's multisig wallet address.", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "serverPubKeyHex": { "type": "string", "example": "02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc" } }, "required": [ "address", "serverPubKeyHex" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/instant/wallet/get-balances": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Get balances", "description": "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.", "tags": [ "Wallet" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "description": "Optional fiat currency for the converted balance fields (e.g. `USD`).", "example": "USD" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "onChainBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Total balance seen on-chain (confirmed + unconfirmed), in satoshis." }, "confirmedOnChainBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "On-chain balance with at least one confirmation, in satoshis." }, "unconfirmedOnChainBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Net mempool delta for the wallet address (incoming 0-conf outputs minus the value of its inputs spent by mempool txs), in satoshis. Can be negative right after an outgoing transaction — do NOT add it to `confirmedOnChainBalance`, use `pendingChangeBalance` / `totalBalance` for pending funds." }, "signedBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Outgoing amount + fee of transactions the user has already signed that are not yet connected into the UTXO graph and hold no UTXO lock, in satoshis. Funds reserved by a lock are reported under `lockedBalance` instead, so the two buckets never overlap." }, "lockedBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Balance locked in pending payments / withdrawals (unspent outputs with an active UTXO lock), in satoshis." }, "pendingChangeBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Our own change from broadcast but still unconfirmed transactions (e.g. the change of a withdrawal), in satoshis. Not yet spendable, so it is excluded from `leftBalance` and included in `totalBalance`." }, "leftBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Spendable balance available for new transactions, in satoshis: sum of confirmed unlocked outputs minus `signedBalance`, floored at 0. Note that `confirmedOnChainBalance` still counts locked outputs, so `leftBalance` is not simply `confirmedOnChainBalance - lockedBalance - signedBalance`." }, "totalBalance": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "`leftBalance + pendingChangeBalance`, in satoshis — everything the wallet owns and is not spending, including change that is still waiting for a confirmation." }, "leftBalanceInUsd": { "type": [ "number", "null" ], "description": "`leftBalance` converted to USD (null if no rate is available).", "example": 50000 }, "leftBalanceInCurrency": { "type": [ "number", "null" ], "description": "`leftBalance` converted to the requested `currency` (null if no rate is available).", "example": 50000 } }, "required": [ "onChainBalance", "confirmedOnChainBalance", "unconfirmedOnChainBalance", "signedBalance", "lockedBalance", "pendingChangeBalance", "leftBalance", "totalBalance", "leftBalanceInUsd", "leftBalanceInCurrency" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/instant/transaction/get-payment": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Get payment", "description": "Returns the current state of a payment by `paymentId`, including its `status`, amounts, merchant / POS details, and `qrString`. Poll this to track a payment until it is paid or expired.", "tags": [ "Payments" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Transaction (payment) identifier — the `paymentId` returned by **Create payment**.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "paymentId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Transaction (payment) identifier — the `paymentId` returned by **Create payment**.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "initiated", "detected", "paid", "failed", "expired", "canceled", "cleared" ], "description": "Payment status. One of `initiated`, `detected`, `paid`, `failed`, `expired`, `canceled`, `cleared`.", "example": "initiated" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" }, "posTerminalLabel": { "type": [ "string", "null" ], "description": "Label of the POS terminal (may be null).", "example": "Front desk" }, "posTerminalLocation": { "type": [ "string", "null" ], "description": "Location of the POS terminal (may be null).", "example": "Lisbon, PT" }, "merchantDisplayName": { "type": [ "string", "null" ], "description": "Merchant's public display name (may be null).", "example": "Satoshi Coffee" }, "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "description": { "type": "string", "description": "Description shown to the payer (optional).", "example": "Order #1024" }, "amountSats": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "description": "Amount to pay, in satoshis.", "example": "string" }, "btcPriceInUsd": { "type": "number", "description": "BTC/USD price captured when the payment was created.", "example": 65000 }, "btcPriceInCurrency": { "type": "number", "description": "BTC price in the payment's `currency`, captured when the payment was created.", "example": 65000 }, "currencySymbol": { "anyOf": [ { "type": "string", "example": "$" }, { "not": {}, "example": {} } ], "description": "Display symbol of the currency, e.g. `$`." }, "amount": { "type": "number", "description": "Amount in the payment's fiat `currency`.", "example": 10 }, "metadata": { "description": "Internal system metadata attached to the payment (reserved; not set by clients).", "example": {} }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "description": "Expiry time as a Unix timestamp (seconds)." }, "qrString": { "type": "string", "description": "Payment encoded as a BIP-21 URI, ready to render as a QR code.", "example": "bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?amount=0.0005" } }, "required": [ "paymentId", "status", "merchantId", "currency", "merchantName", "posTerminalLabel", "posTerminalLocation", "merchantDisplayName", "posTerminalId", "amountSats", "btcPriceInUsd", "btcPriceInCurrency", "amount", "expiresAt", "qrString" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Description shown to the payer (optional).", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"$BASE_URL/instant/transaction/get-payment\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"paymentId\": \"pay_…\"\n}'" } ] } }, "/instant/transaction/list": { "post": { "security": [ { "walletAuth": [] } ], "summary": "List payments", "description": "Returns a paginated list of payment transactions with optional `dateRange` and `status` filters. Each item carries merchant / POS context, fiat and BTC amounts, and on-chain settlement data when available. `totalCount` reflects the filtered total.", "tags": [ "Payments" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of items to return (1–100, default 20).", "example": 20 }, "skip": { "type": "number", "minimum": 0, "default": 0, "description": "Number of items to skip — offset for pagination (default 0).", "example": 0 } }, "additionalProperties": false }, "filters": { "type": "object", "properties": { "dateRange": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0, "description": "Filter from this creation time, Unix timestamp (seconds).", "example": 0 }, "end": { "type": "integer", "minimum": 0, "description": "Filter up to this creation time, Unix timestamp (seconds).", "example": 0 } }, "required": [ "start", "end" ], "additionalProperties": false }, "status": { "type": "array", "items": { "type": "string", "enum": [ "success", "failed", "pending", "cleared" ], "example": "success" }, "description": "Filter by payment transaction status. Values: `success`, `failed`, `pending`, `cleared`." } }, "additionalProperties": false } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Identifier of the payment (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "paymentTxId": { "type": "string", "description": "Id of the payment transaction.", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "status": { "type": "string", "enum": [ "success", "failed", "pending", "cleared" ], "description": "Filter by payment transaction status. Values: `success`, `failed`, `pending`, `cleared`.", "example": "success" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" }, "posTerminalLabel": { "type": [ "string", "null" ], "description": "Label of the POS terminal (may be null).", "example": "Front desk" }, "posTerminalLocation": { "type": [ "string", "null" ], "description": "Location of the POS terminal (may be null).", "example": "Lisbon, PT" }, "merchantDisplayName": { "type": [ "string", "null" ], "description": "Merchant's public display name (may be null).", "example": "Satoshi Coffee" }, "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "description": { "type": [ "string", "null" ], "description": "Description shown to the payer (may be null).", "example": "Order #1024" }, "metadata": { "description": "Internal system metadata attached to the payment (reserved; not set by clients).", "example": {} }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "btcPriceInUsd": { "type": "number", "description": "BTC/USD price captured when the payment was created.", "example": 65000 }, "btcPriceInCurrency": { "type": "number", "description": "BTC price in the payment's `currency`, captured when the payment was created.", "example": 65000 }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" }, "amount": { "type": "number", "description": "Amount in the payment's fiat `currency`.", "example": 10 }, "currencySymbol": { "anyOf": [ { "type": "string", "example": "$" }, { "not": {}, "example": {} } ], "description": "Display symbol of the currency, e.g. `$`." }, "onChain": { "anyOf": [ { "type": "object", "properties": { "tx": { "type": "string", "description": "On-chain Bitcoin transaction id (hex).", "example": "02000000000101a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f6071829ffffffff" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "feeSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Network fee for the transaction, in satoshis." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "blockNumber": { "type": [ "number", "null" ], "description": "Height of the block that confirmed the transaction; null while unconfirmed.", "example": 845000 } }, "required": [ "tx", "amountSats", "feeSats", "createdAt", "blockNumber" ], "additionalProperties": false }, { "type": "null", "example": null } ], "description": "On-chain settlement details, or null if not yet settled." } }, "required": [ "paymentId", "paymentTxId", "status", "merchantId", "merchantName", "posTerminalLabel", "posTerminalLocation", "merchantDisplayName", "posTerminalId", "amountSats", "description", "createdAt", "btcPriceInUsd", "btcPriceInCurrency", "currency", "amount", "onChain" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "Total number of records matching the filters.", "example": 0 } }, "required": [ "items", "totalCount" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Description shown to the payer (may be null).", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/instant/psbt/build-transaction-to-sign-payment": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Build payment transaction", "description": "Builds the unsigned PSBT that settles a payment. Pass the `paymentId`; the response returns a `jobId`, the `psbtBase64` to sign with the wallet key, and a `summary` of inputs, fee, and change. Sign it client-side, then submit via **Settle payment**.", "tags": [ "Payments" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "The payment to settle, as returned by **Create payment** (`/instant/transaction/create-payment`).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "paymentId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Id of this PSBT build. Pass it with the signed PSBT to **Settle payment**.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "psbtBase64": { "type": "string", "description": "Unsigned transaction as a base64-encoded PSBT (BIP-174). Sign it with the wallet key.", "example": "cHNidP8BAHECAAAAAfYI0kF1pQ0i3xL0AAAAAAD9////AsBdAQAAAAAAFgAUdR5" }, "summary": { "type": "object", "properties": { "fromAddress": { "type": "string", "description": "Source address — the user's multisig wallet.", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "toAddress": { "type": "string", "description": "Destination address — the treasury (settlement) wallet.", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "feeRateSatVb": { "type": "number", "description": "Fee rate in satoshis per virtual byte (sat/vB).", "example": 50000 }, "estVsize": { "type": "number", "description": "Estimated virtual size of the transaction, in vbytes.", "example": 140 }, "feeSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Network fee for the transaction, in satoshis." }, "changeSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Change returned to the wallet, in satoshis." }, "inputCount": { "type": "number", "description": "Number of inputs selected for the transaction.", "example": 0 } }, "required": [ "fromAddress", "toAddress", "amountSats", "feeRateSatVb", "estVsize", "feeSats", "changeSats", "inputCount" ], "additionalProperties": false } }, "required": [ "jobId", "psbtBase64", "summary" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"$BASE_URL/instant/psbt/build-transaction-to-sign-payment\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"paymentId\": \"pay_…\"\n}'" } ] } }, "/instant/transaction/pay-and-sign-pre-authorized-transaction": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Settle payment", "description": "Submits the signed payment PSBT to settle a pre-authorized payment. Send the `paymentId` and `jobId` from **Build payment transaction** together with the `signedPsbtBase64`. Returns the resulting `paymentTxId` and a success flag.", "tags": [ "Payments" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "The payment being settled (from **Create payment**).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "jobId": { "type": "string", "description": "The `jobId` from **Build payment transaction** (`/instant/psbt/build-transaction-to-sign-payment`).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "signedPsbtBase64": { "type": "string", "description": "The PSBT from **Build payment transaction**, signed with the wallet key, base64-encoded.", "example": "cHNidP8BAHECAAAAAfYI0kF1pQ0i3xL0AAAAAAD9////AsBdAQAAAAAAFgAUdR5" } }, "required": [ "jobId", "signedPsbtBase64" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "The payment being settled (from **Create payment**).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "paymentTxId": { "type": "string", "description": "Id of the resulting payment transaction.", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "success": { "type": "boolean", "description": "Whether the payment was accepted and broadcast.", "example": true } }, "required": [ "paymentId", "paymentTxId", "success" ], "additionalProperties": false, "description": "Whether the payment was accepted and broadcast." } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"$BASE_URL/instant/transaction/pay-and-sign-pre-authorized-transaction\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"paymentId\": \"pay_…\",\n \"jobId\": \"job_…\",\n \"signedPsbtBase64\": \"cHNidP8B…\"\n}'" } ] } }, "/instant/transaction/on-chain-list": { "post": { "security": [ { "walletAuth": [] } ], "summary": "List on-chain transactions", "description": "Returns the wallet's on-chain transactions with optional `dateRange` and `type` filters. Each entry includes the tx id, amounts, fee, block number (null while unconfirmed), and the payments settled by that transaction.", "tags": [ "Payments" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "dateRange": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0, "description": "Filter from this creation time, Unix timestamp (seconds).", "example": 0 }, "end": { "type": "integer", "minimum": 0, "description": "Filter up to this creation time, Unix timestamp (seconds).", "example": 0 } }, "required": [ "start", "end" ], "additionalProperties": false }, "type": { "type": "array", "items": { "type": "string", "enum": [ "in", "out", "self" ], "example": "in" }, "description": "Filter by transaction direction. Values: `in`, `out`, `self`." } }, "additionalProperties": false } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "tx": { "type": "string", "description": "On-chain Bitcoin transaction id (hex).", "example": "02000000000101a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f6071829ffffffff" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "feeSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Network fee for the transaction, in satoshis." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "blockNumber": { "type": [ "number", "null" ], "description": "Height of the block that confirmed the transaction; null while unconfirmed.", "example": 845000 }, "type": { "type": "string", "enum": [ "in", "out", "self" ], "description": "Filter by transaction direction. Values: `in`, `out`, `self`.", "example": "in" }, "paymentTxs": { "type": "array", "items": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Identifier of the payment (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "paymentTxId": { "type": "string", "description": "Identifier of the payment transaction (UUID).", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "status": { "type": "string", "enum": [ "success", "failed", "pending", "cleared" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "success" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" }, "posTerminalLabel": { "type": [ "string", "null" ], "description": "Label of the POS terminal (may be null).", "example": "Front desk" }, "posTerminalLocation": { "type": [ "string", "null" ], "description": "Location of the POS terminal (may be null).", "example": "Lisbon, PT" }, "merchantDisplayName": { "type": [ "string", "null" ], "description": "Merchant's public display name (may be null).", "example": "Satoshi Coffee" }, "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description.", "example": "Order #1024" }, "metadata": { "description": "Internal system metadata attached to the payment (reserved; not set by clients).", "example": {} }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "btcPriceInUsd": { "type": "number", "description": "BTC/USD price captured when the payment was created.", "example": 65000 }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" }, "amount": { "type": "number", "description": "Amount in the payment's fiat `currency`.", "example": 10 }, "currencySymbol": { "anyOf": [ { "type": "string", "example": "$" }, { "not": {}, "example": {} } ], "description": "Display symbol of the currency, e.g. `$`." }, "btcPriceInCurrency": { "type": "number", "description": "BTC price in the payment's `currency`, captured when the payment was created.", "example": 65000 } }, "required": [ "paymentId", "paymentTxId", "status", "merchantId", "merchantName", "posTerminalLabel", "posTerminalLocation", "merchantDisplayName", "posTerminalId", "amountSats", "description", "createdAt", "btcPriceInUsd", "currency", "amount", "btcPriceInCurrency" ], "additionalProperties": false } } }, "required": [ "tx", "amountSats", "feeSats", "createdAt", "blockNumber", "type", "paymentTxs" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/multisig/onchain/get-data-to-withdraw": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Get withdrawal parameters", "description": "Returns everything needed to build a withdrawal PSBT client-side: the multisig descriptor (`m`/`n`, witness script), spendable UTXOs, recommended fee rates (low / medium / high), change script details, and virtual-size parameters for fee estimation.", "tags": [ "Multisig Withdrawal" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "multisig": { "type": "object", "properties": { "m": { "type": "number", "description": "Number of required signatures (the *m* in m-of-n multisig).", "example": 2 }, "n": { "type": "number", "description": "Total number of signers (the *n* in m-of-n multisig).", "example": 3 }, "witnessScript": { "type": "string", "description": "Witness script of the multisig wallet, hex-encoded.", "example": "0014751e76e8199196d454941c45d1b3a323f1433bd6" } }, "required": [ "m", "n", "witnessScript" ], "additionalProperties": false }, "utxos": { "type": "array", "items": { "type": "object", "properties": { "txid": { "type": "string", "description": "On-chain Bitcoin transaction id (hex).", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "vout": { "type": "number", "description": "Index of the referenced output within its transaction.", "example": 0 }, "value": { "type": "number", "description": "Output value, in satoshis.", "example": 50000 }, "scriptPubKey": { "type": "string", "description": "Output script (scriptPubKey), hex-encoded.", "example": "02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc" } }, "required": [ "txid", "vout", "value", "scriptPubKey" ], "additionalProperties": false }, "description": "Spendable UTXOs of the wallet, for building the withdrawal client-side." }, "feeRateSatVb": { "type": "object", "properties": { "law": { "type": "number", "description": "Low-priority fee rate (sat/vB).", "example": 12 }, "medium": { "type": "number", "description": "Medium-priority fee rate (sat/vB).", "example": 12 }, "high": { "type": "number", "description": "High-priority fee rate (sat/vB).", "example": 12 } }, "required": [ "law", "medium", "high" ], "additionalProperties": false, "description": "Fee rate in satoshis per virtual byte (sat/vB)." }, "change": { "type": "object", "properties": { "scriptPubKeyHex": { "type": "string", "description": "Output script (scriptPubKey), hex-encoded.", "example": "02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc" }, "dustThreshold": { "type": "number", "description": "Minimum output value in satoshis; change below this is treated as dust and dropped.", "example": 546 } }, "required": [ "scriptPubKeyHex", "dustThreshold" ], "additionalProperties": false }, "params": { "type": "object", "properties": { "vSizeP2wsh20f3In": { "type": "number", "description": "Virtual size added per 2-of-3 P2WSH input, in vbytes.", "example": 140 }, "vSizeP2wpkhOut": { "type": "number", "description": "Virtual size added per P2WPKH output, in vbytes.", "example": 140 }, "vSizeP2wshOut": { "type": "number", "description": "Virtual size added per P2WSH output, in vbytes.", "example": 140 }, "txOverhead": { "type": "number", "description": "Fixed transaction overhead, in vbytes.", "example": 140 } }, "required": [ "vSizeP2wsh20f3In", "vSizeP2wpkhOut", "vSizeP2wshOut", "txOverhead" ], "additionalProperties": false } }, "required": [ "multisig", "utxos", "feeRateSatVb", "change", "params" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/multisig/onchain/build-psbt-to-withdraw": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Build withdrawal transaction", "description": "Builds an unsigned withdrawal PSBT to `toAddress`. Provide either `amountSats` or `sendMax`, plus a `fee.feeRateSatVb`. Optionally pin inputs with `selectUtxos` and enable replace-by-fee with `rbf`. Returns the `jobId`, `psbtBase64`, and a `summary` (fee, vsize, change, inputs). Co-sign, then submit via **Broadcast withdrawal**.", "tags": [ "Multisig Withdrawal" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "toAddress": { "type": "string", "description": "Destination Bitcoin address for the funds.", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "sendMax": { "type": "boolean", "description": "If true, sweeps the entire spendable balance to `toAddress` and ignores the amount.", "example": true }, "fee": { "type": "object", "properties": { "feeRateSatVb": { "type": "number", "exclusiveMinimum": 0, "description": "Fee rate in satoshis per virtual byte (sat/vB).", "example": 50000 } }, "required": [ "feeRateSatVb" ], "additionalProperties": false }, "selectUtxos": { "type": "array", "items": { "type": "object", "properties": { "txid": { "type": "string", "description": "On-chain Bitcoin transaction id (hex).", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "vout": { "type": "integer", "minimum": 0, "description": "Index of the referenced output within its transaction.", "example": 0 } }, "required": [ "txid", "vout" ], "additionalProperties": false }, "description": "Optional list of specific UTXOs to spend. If omitted, coins are selected automatically." }, "rbf": { "type": "boolean", "description": "Enable Replace-By-Fee (BIP-125) so the transaction can be fee-bumped later.", "example": true } }, "required": [ "toAddress", "fee" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Id of this withdrawal build. Pass it with the co-signed PSBT to **Broadcast withdrawal**.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "psbtBase64": { "type": "string", "description": "Unsigned transaction as a base64-encoded PSBT (BIP-174). Sign it with the wallet key.", "example": "cHNidP8BAHECAAAAAfYI0kF1pQ0i3xL0AAAAAAD9////AsBdAQAAAAAAFgAUdR5" }, "summary": { "type": "object", "properties": { "toAddress": { "type": "string", "description": "Destination Bitcoin address for the funds.", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "feeSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Network fee for the transaction, in satoshis." }, "feeRateSatVb": { "type": "number", "exclusiveMinimum": 0, "description": "Fee rate in satoshis per virtual byte (sat/vB).", "example": 50000 }, "vsize": { "type": "integer", "exclusiveMinimum": 0, "description": "Estimated virtual size of the transaction, in vbytes.", "example": 140 }, "change": { "type": "object", "properties": { "valueSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Change output value, in satoshis." } }, "required": [ "valueSats" ], "additionalProperties": false }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "txid": { "type": "string", "description": "On-chain Bitcoin transaction id (hex).", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "vout": { "type": "integer", "minimum": 0, "description": "Index of the referenced output within its transaction.", "example": 0 }, "value": { "type": "integer", "exclusiveMinimum": 0, "description": "Output value, in satoshis.", "example": 50000 } }, "required": [ "txid", "vout", "value" ], "additionalProperties": false } } }, "required": [ "toAddress", "amountSats", "feeSats", "feeRateSatVb", "vsize", "inputs" ], "additionalProperties": false } }, "required": [ "jobId", "psbtBase64", "summary" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"$BASE_URL/multisig/onchain/build-psbt-to-withdraw\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"toAddress\": \"bc1q…\",\n \"amountSats\": 50000,\n \"fee\": {\n \"feeRateSatVb\": 12\n },\n \"rbf\": true\n}'" } ] } }, "/multisig/onchain/confirm-withdraw": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Broadcast withdrawal", "description": "Broadcasts a co-signed withdrawal. Submit the `jobId` from **Build withdrawal PSBT** and the `signedPsbtBase64`. Returns the broadcast `txid` (and `txHex` when available).", "tags": [ "Multisig Withdrawal" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "description": "The `jobId` from **Build withdrawal transaction** (`/multisig/onchain/build-psbt-to-withdraw`).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "signedPsbtBase64": { "type": "string", "description": "The withdrawal PSBT, co-signed, base64-encoded.", "example": "cHNidP8BAHECAAAAAfYI0kF1pQ0i3xL0AAAAAAD9////AsBdAQAAAAAAFgAUdR5" } }, "required": [ "jobId", "signedPsbtBase64" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "txid": { "type": "string", "description": "On-chain Bitcoin transaction id (hex).", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "txHex": { "type": "string", "description": "Raw signed transaction, hex-encoded (available once broadcast).", "example": "02000000000101a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f6071829ffffffff" } }, "required": [ "txid" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"$BASE_URL/multisig/onchain/confirm-withdraw\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"jobId\": \"job_…\",\n \"signedPsbtBase64\": \"cHNidP8B…\"\n}'" } ] } }, "/selfcustody/config": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Get network parameters", "description": "Returns the parameters a client needs to work with BTC locally: `network` (mainnet / testnet), `nativeSymbol` and `nativeDecimals`, the default derivation path, the dust threshold in satoshis, and explorer URL templates for addresses and transactions (both contain `{value}` for the client to substitute). These describe the INSTALLATION — one deployment serves exactly one network — so there is no chain or token registry to query.", "tags": [ "Self-Custody Wallet" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "mainnet", "testnet" ], "example": "mainnet" }, "nativeSymbol": { "type": "string", "example": "string" }, "nativeDecimals": { "type": "integer", "minimum": 0, "example": 0 }, "defaultDerivationPath": { "type": "string", "example": "string" }, "dustThresholdSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "explorerAddressUrlTemplate": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "explorerTxUrlTemplate": { "type": "string", "example": "string" } }, "required": [ "network", "nativeSymbol", "nativeDecimals", "defaultDerivationPath", "dustThresholdSats", "explorerAddressUrlTemplate", "explorerTxUrlTemplate" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/selfcustody/wallet/register": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Register wallet", "description": "Creates a self-custody wallet for the public key in the JWT. The private key never reaches the server. One public key maps to at most one wallet: calling this again returns the existing `walletId` with `created: false` and does NOT overwrite `name`. A freshly registered wallet has no addresses — add them with `/selfcustody/address/add`.", "tags": [ "Self-Custody Wallet" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "example": "Satoshi Coffee" } }, "required": [ "name" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "walletId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "created": { "type": "boolean", "example": true } }, "required": [ "walletId", "created" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/selfcustody/wallet/get": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Get wallet", "description": "Returns the wallet of the authenticated public key with its addresses, each carrying the derivation path and index the client used. An empty `addresses` list is a valid state, not an error. `monitoredAt: null` signals an address that never reached the indexer — balances and history for it would be empty, so it is surfaced rather than hidden.", "tags": [ "Self-Custody Wallet" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "name": { "type": "string", "example": "Satoshi Coffee" }, "createdAt": { "type": "string", "description": "Creation time as a Unix timestamp (seconds).", "example": "string" }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "address": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "pubkeyHex": { "type": "string", "example": "02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc" }, "derivationPath": { "type": "string", "example": "string" }, "addressIndex": { "type": "integer", "minimum": 0, "example": 0 }, "monitoredAt": { "type": [ "string", "null" ], "example": "string" } }, "required": [ "id", "address", "pubkeyHex", "derivationPath", "addressIndex", "monitoredAt" ], "additionalProperties": false } } }, "required": [ "id", "name", "createdAt", "addresses" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/selfcustody/wallet/get-balances": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Get balances", "description": "Returns per-address balances split by availability, all in satoshis: `spendableSats` (confirmed and unlocked — the only funds that can be spent now), `unconfirmedSats` (outputs of transactions not yet in a block, including our own change), `lockedSats` (outputs reserved by an unfinished `/selfcustody/transaction/build`) and `totalSats`, which is the sum of the three. The buckets never overlap, so they can be displayed side by side. `spendableInUsd` is `null` when a rate is unavailable — that is not a request failure, the satoshi amounts are still exact. Pass `addressId` to narrow to one address.", "tags": [ "Self-Custody Wallet" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "addressId": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "balances": { "type": "array", "items": { "type": "object", "properties": { "addressId": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "address": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "spendableSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "unconfirmedSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "lockedSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "totalSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "spendableInUsd": { "type": [ "number", "null" ], "example": 0 } }, "required": [ "addressId", "address", "spendableSats", "unconfirmedSats", "lockedSats", "totalSats", "spendableInUsd" ], "additionalProperties": false } }, "updatedAt": { "type": "string", "example": "string" } }, "required": [ "balances", "updatedAt" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/selfcustody/wallet/resync": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Resync with the blockchain", "description": "Forces an out-of-schedule resync of the wallet's addresses. Pass `addressId` to resync one, or `deep: true` to re-read the whole history instead of only new blocks. Results are reported per address: a failure on one address comes back as `ok: false` with an `error` rather than failing the whole request, so a partial refresh is never mistaken for a complete one.", "tags": [ "Self-Custody Wallet" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "addressId": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "deep": { "type": "boolean", "default": false, "example": true } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "addressId": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "address": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "ok": { "type": "boolean", "example": true }, "error": { "type": [ "string", "null" ], "example": "string" }, "syncedTillBlock": { "anyOf": [ { "type": "integer", "minimum": 0, "example": 0 }, { "type": "null", "example": null } ] }, "ingestedTxCount": { "type": "integer", "minimum": 0, "example": 0 } }, "required": [ "addressId", "address", "ok", "error", "syncedTillBlock", "ingestedTxCount" ], "additionalProperties": false } } }, "required": [ "results" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/selfcustody/address/add": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Add address", "description": "Registers an address the CLIENT derived and starts tracking it on-chain. The server verifies that `address` really derives from `pubkeyHex` and rejects the request otherwise — without that check a wallet could claim someone else's address. The call is idempotent (`created: false` on repeat) and only succeeds once the address is actually being tracked: an untracked address would silently report a zero balance.", "tags": [ "Self-Custody Wallet" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "pubkeyHex": { "type": "string", "example": "02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc" }, "derivationPath": { "type": "string", "example": "string" }, "addressIndex": { "type": "integer", "minimum": 0, "example": 0 }, "ownershipChallengeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "ownershipSignature": { "type": "string", "pattern": "^[0-9a-fA-F]{128}$", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" } }, "required": [ "address", "pubkeyHex", "derivationPath", "addressIndex" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "addressId": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "address": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "created": { "type": "boolean", "example": true }, "monitoredAt": { "type": "string", "example": "string" }, "wasAlreadyMonitored": { "type": "boolean", "example": true } }, "required": [ "addressId", "address", "created", "monitoredAt", "wasAlreadyMonitored" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/selfcustody/fee/estimate": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Estimate fee", "description": "Returns recommended fee rates as three tiers (`slow` / `standard` / `fast`) in sat/vByte, sourced from a mempool estimator, with `updatedAt` telling how fresh they are — a cached rate is served when the source is unreachable, and its age is shown rather than hidden. Pass `addressId` AND `amountSats` together to also get `exact`: the fee for that address's real UTXO set, the `inputCount` and `vBytes` behind it, `recipientAmountSats`, and `maxSendableSats`. The last one is what a “Max” button should send — for BTC `fee = feeRate × vBytes` and `vBytes` depends on the input count, which only the server knows.", "tags": [ "Self-Custody Wallet" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "addressId": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "feeIncluded": { "type": "boolean", "default": false, "example": true } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "slow": { "type": "object", "properties": { "feeRateSatVb": { "type": "number", "exclusiveMinimum": 0, "description": "Fee rate in satoshis per virtual byte (sat/vB).", "example": 50000 }, "estimatedSecs": { "type": "integer", "minimum": 0, "example": 0 }, "exact": { "anyOf": [ { "type": "object", "properties": { "feeSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Network fee for the transaction, in satoshis." }, "inputCount": { "type": "integer", "minimum": 0, "description": "Number of inputs selected for the transaction.", "example": 0 }, "vBytes": { "type": "integer", "minimum": 0, "example": 0 }, "recipientAmountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "maxSendableSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "sufficientFunds": { "type": "boolean", "example": true } }, "required": [ "feeSats", "inputCount", "vBytes", "recipientAmountSats", "maxSendableSats", "sufficientFunds" ], "additionalProperties": false }, { "type": "null", "example": null } ] } }, "required": [ "feeRateSatVb", "estimatedSecs", "exact" ], "additionalProperties": false }, "standard": { "type": "object", "properties": { "feeRateSatVb": { "type": "number", "exclusiveMinimum": 0, "description": "Fee rate in satoshis per virtual byte (sat/vB).", "example": 50000 }, "estimatedSecs": { "type": "integer", "minimum": 0, "example": 0 }, "exact": { "anyOf": [ { "type": "object", "properties": { "feeSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Network fee for the transaction, in satoshis." }, "inputCount": { "type": "integer", "minimum": 0, "description": "Number of inputs selected for the transaction.", "example": 0 }, "vBytes": { "type": "integer", "minimum": 0, "example": 0 }, "recipientAmountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "maxSendableSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "sufficientFunds": { "type": "boolean", "example": true } }, "required": [ "feeSats", "inputCount", "vBytes", "recipientAmountSats", "maxSendableSats", "sufficientFunds" ], "additionalProperties": false }, { "type": "null", "example": null } ] } }, "required": [ "feeRateSatVb", "estimatedSecs", "exact" ], "additionalProperties": false }, "fast": { "type": "object", "properties": { "feeRateSatVb": { "type": "number", "exclusiveMinimum": 0, "description": "Fee rate in satoshis per virtual byte (sat/vB).", "example": 50000 }, "estimatedSecs": { "type": "integer", "minimum": 0, "example": 0 }, "exact": { "anyOf": [ { "type": "object", "properties": { "feeSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Network fee for the transaction, in satoshis." }, "inputCount": { "type": "integer", "minimum": 0, "description": "Number of inputs selected for the transaction.", "example": 0 }, "vBytes": { "type": "integer", "minimum": 0, "example": 0 }, "recipientAmountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "maxSendableSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "sufficientFunds": { "type": "boolean", "example": true } }, "required": [ "feeSats", "inputCount", "vBytes", "recipientAmountSats", "maxSendableSats", "sufficientFunds" ], "additionalProperties": false }, { "type": "null", "example": null } ] } }, "required": [ "feeRateSatVb", "estimatedSecs", "exact" ], "additionalProperties": false }, "updatedAt": { "type": "string", "example": "string" } }, "required": [ "slow", "standard", "fast", "updatedAt" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/selfcustody/transaction/build": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Build unsigned transaction", "description": "Builds an unsigned PSBT for the client to sign locally; the private key never reaches the server. Set `feeIncluded: false` to add the fee on top of `amountSats`, or `true` to take it out of that amount — `recipientAmountSats` reports what the recipient actually receives. Change below the dust threshold is added to the fee instead of creating an unspendable output. The selected outputs are LOCKED until `expiresAt`, so a concurrent build cannot pick the same ones; `quoteId` identifies both the quote and that lock.", "tags": [ "Self-Custody Wallet" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "addressId": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "toAddress": { "type": "string", "minLength": 1, "description": "Destination Bitcoin address for the funds.", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "feeRateSatVb": { "type": "number", "exclusiveMinimum": 0, "description": "Fee rate in satoshis per virtual byte (sat/vB).", "example": 50000 }, "feeIncluded": { "type": "boolean", "example": true } }, "required": [ "addressId", "toAddress", "amountSats", "feeRateSatVb", "feeIncluded" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "quoteId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "psbtBase64": { "type": "string", "description": "Unsigned transaction as a base64-encoded PSBT (BIP-174). Sign it with the wallet key.", "example": "cHNidP8BAHECAAAAAfYI0kF1pQ0i3xL0AAAAAAD9////AsBdAQAAAAAAFgAUdR5" }, "feeSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Network fee for the transaction, in satoshis." }, "recipientAmountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "changeSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Change returned to the wallet, in satoshis." }, "inputCount": { "type": "integer", "exclusiveMinimum": 0, "description": "Number of inputs selected for the transaction.", "example": 0 }, "vBytes": { "type": "integer", "exclusiveMinimum": 0, "example": 0 }, "expiresAt": { "type": "string", "description": "Expiry time as a Unix timestamp (seconds).", "example": "string" } }, "required": [ "quoteId", "psbtBase64", "feeSats", "recipientAmountSats", "changeSats", "inputCount", "vBytes", "expiresAt" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/selfcustody/transaction/broadcast": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Broadcast signed transaction", "description": "Submits the transaction the client signed and finalized — `rawTx` is signed transaction hex, not a PSBT — and releases the lock on the outputs it spent. Only an unexpired `quoteId` is accepted; past `expiresAt` the quote must be rebuilt. Retrying with the same `rawTx` is safe and returns `wasAlreadySubmitted: true`: the network may have accepted the first attempt while the response never reached the client.", "tags": [ "Self-Custody Wallet" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "rawTx": { "type": "string", "minLength": 1, "example": "string" } }, "required": [ "quoteId", "rawTx" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "txid": { "type": "string", "description": "On-chain Bitcoin transaction id (hex).", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "wasAlreadySubmitted": { "type": "boolean", "example": true } }, "required": [ "txid", "wasAlreadySubmitted" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/selfcustody/transaction/list": { "post": { "security": [ { "walletAuth": [] } ], "summary": "List transactions", "description": "Returns transaction history newest-first with a `nextCursor` for the next page (`null` on the last one); transactions not yet in a block come first. Amounts are stated from the wallet's side: for an incoming transaction what arrived, for an outgoing one what went to recipients excluding our own change. `feeSats` is set only on outgoing transactions — the spender pays the fee — and may be `null` when not all inputs are known to the indexer, since reporting zero there would be wrong. Filter with `statuses` and `directions`.", "tags": [ "Self-Custody Wallet" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "addressId": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "cursor": { "type": "string", "minLength": 1, "example": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "example": 20 }, "statuses": { "type": "array", "items": { "type": "string", "enum": [ "pending", "confirmed", "failed" ], "example": "pending" } }, "directions": { "type": "array", "items": { "type": "string", "enum": [ "in", "out", "self" ], "example": "in" } } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "txs": { "type": "array", "items": { "type": "object", "properties": { "txid": { "type": "string", "description": "On-chain Bitcoin transaction id (hex).", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "addressId": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "direction": { "type": "string", "enum": [ "in", "out", "self" ], "example": "in" }, "status": { "type": "string", "enum": [ "pending", "confirmed", "failed" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "pending" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "feeSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ], "description": "Network fee for the transaction, in satoshis." }, "counterpartyAddresses": { "type": "array", "items": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" } }, "blockHeight": { "anyOf": [ { "type": "integer", "minimum": 0, "example": 845000 }, { "type": "null", "example": null } ] }, "blockTime": { "type": [ "string", "null" ], "example": "string" }, "confirmations": { "type": "integer", "minimum": 0, "example": 0 } }, "required": [ "txid", "addressId", "direction", "status", "amountSats", "feeSats", "counterpartyAddresses", "blockHeight", "blockTime", "confirmations" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ], "example": "string" } }, "required": [ "txs", "nextCursor" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/selfcustody/transaction/get": { "post": { "security": [ { "walletAuth": [] } ], "summary": "Get transaction", "description": "Returns one transaction by `txid`, in the same shape as the list entries, including `confirmations`. Use it to follow a send you just broadcast without refetching the whole history — and so that a dropped websocket cannot leave a transfer stuck on “processing” forever.", "tags": [ "Self-Custody Wallet" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "txid": { "type": "string", "description": "On-chain Bitcoin transaction id (hex).", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" } }, "required": [ "txid" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "tx": { "type": "object", "properties": { "txid": { "type": "string", "description": "On-chain Bitcoin transaction id (hex).", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "addressId": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "direction": { "type": "string", "enum": [ "in", "out", "self" ], "example": "in" }, "status": { "type": "string", "enum": [ "pending", "confirmed", "failed" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "pending" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "feeSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ], "description": "Network fee for the transaction, in satoshis." }, "counterpartyAddresses": { "type": "array", "items": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" } }, "blockHeight": { "anyOf": [ { "type": "integer", "minimum": 0, "example": 845000 }, { "type": "null", "example": null } ] }, "blockTime": { "type": [ "string", "null" ], "example": "string" }, "confirmations": { "type": "integer", "minimum": 0, "example": 0 } }, "required": [ "txid", "addressId", "direction", "status", "amountSats", "feeSats", "counterpartyAddresses", "blockHeight", "blockTime", "confirmations" ], "additionalProperties": false, "description": "On-chain Bitcoin transaction id (hex)." } }, "required": [ "tx" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/payment/cancel": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Cancel payment", "description": "Cancels a payment that has not been paid yet — use it when the order is dropped on your side. Only `initiated` and `expired` payments can be canceled; once funds are seen on-chain (`detected`) or confirmed (`paid`) the call fails with `payment_not_cancelable`. Cancelling an already-canceled payment succeeds and changes nothing, so retries are safe. Unlike `expired`, `canceled` is terminal: the watcher stops following the address, so late funds will not flip it to `paid`.", "tags": [ "Payments" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Identifier of the payment (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "paymentId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Identifier of the payment (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "initiated", "detected", "paid", "failed", "expired", "canceled", "cleared" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "initiated" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" }, "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "posTerminalLabel": { "type": [ "string", "null" ], "description": "Label of the POS terminal (may be null).", "example": "Front desk" }, "posTerminalLocation": { "type": [ "string", "null" ], "description": "Location of the POS terminal (may be null).", "example": "Lisbon, PT" }, "merchantDisplayName": { "type": [ "string", "null" ], "description": "Merchant's public display name (may be null).", "example": "Satoshi Coffee" }, "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "externalId": { "anyOf": [ { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "type": "null", "example": null } ] }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "amountSats": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "description": "Amount in satoshis.", "example": "string" }, "btcPriceInUsd": { "type": "number", "description": "BTC/USD price captured when the payment was created.", "example": 65000 }, "btcPriceInCurrency": { "type": "number", "description": "BTC price in the payment's `currency`, captured when the payment was created.", "example": 65000 }, "currencySymbol": { "anyOf": [ { "type": "string", "example": "$" }, { "not": {}, "example": {} } ], "description": "Display symbol of the currency, e.g. `$`." }, "amount": { "type": "number", "description": "Amount in the payment's fiat `currency`.", "example": 10 }, "metadata": { "description": "Internal system metadata attached to the payment (reserved; not set by clients).", "example": {} }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "description": "Expiry time as a Unix timestamp (seconds)." }, "qrString": { "type": "string", "description": "Payment encoded as a BIP-21 URI, ready to render as a QR code.", "example": "bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?amount=0.0005" }, "version": { "type": "integer", "minimum": 0, "example": 0 }, "transactions": { "type": "array", "items": { "type": "object", "properties": { "txid": { "type": "string", "description": "On-chain Bitcoin transaction id (hex) of this receipt. Look it up in any block explorer to show the payer their transaction.", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "amountSats": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "description": "What this transaction paid into **this payment's** address, in satoshis — not the transaction's total, which may pay other outputs as well.", "example": "string" }, "blockHeight": { "anyOf": [ { "type": "number", "example": 845000 }, { "type": "null", "example": null } ], "description": "Height of the block that included the transaction; `null` while it is still in the mempool." }, "blockTime": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "description": "Timestamp of that block, Unix seconds; `null` while the transaction is still in the mempool. Historical payments confirmed before this field existed report `null` permanently." }, "confirmations": { "anyOf": [ { "type": "integer", "minimum": 0, "example": 0 }, { "type": "null", "example": null } ], "description": "Confirmations as of **now**, not as of the moment the payment was paid, so the value keeps growing. `0` — seen but not in a block yet. `null` — the current chain tip is not known to us right now, so the count cannot be stated; do not render it as zero, the transaction may well be deeply confirmed. The remaining fields are unaffected." }, "feeSats": { "anyOf": [ { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "example": "string" }, { "type": "null", "example": null } ], "description": "Network fee the payer paid for this transaction, in satoshis; `null` when it is not known to us." } }, "required": [ "txid", "amountSats", "blockHeight", "blockTime", "confirmations", "feeSats" ], "additionalProperties": false }, "default": [], "description": "On-chain transactions observed paying this payment, freshest first. Empty until something is seen — and empty is a normal state for a payment in `initiated`. More than one element means the payer sent more than one transaction (an overpayment or a top-up); sum `amountSats` across the list to get what actually arrived. Identical for both payment routes: an in-app payment reports its single transaction here just like one paid from an external wallet." }, "paidAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "default": null, "description": "When the payment was paid, Unix timestamp (seconds); `null` until then. This is the payment's settlement time — for when a single transaction was mined see `transactions[].blockTime`." } }, "required": [ "paymentId", "status", "merchantId", "currency", "merchantName", "storeId", "posTerminalLabel", "posTerminalLocation", "merchantDisplayName", "posTerminalId", "externalId", "amountSats", "btcPriceInUsd", "btcPriceInCurrency", "amount", "expiresAt", "qrString", "version" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"$BASE_URL/merchant/payment/cancel\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"paymentId\": \"pay_…\"\n}'" } ] } } }, "webhooks": {}, "tags": [ { "name": "Authentication", "description": "Challenge–response authentication. Request a message to sign with the wallet key, exchange the signature for a JWT pair, and refresh it." }, { "name": "Wallet", "description": "Wallet lifecycle and read access: register a device key, resolve the multisig address, and read balances and UTXOs." }, { "name": "Payments", "description": "Create and inspect payments, list payment history, and build / submit the signed transaction that settles a payment." }, { "name": "Multisig Withdrawal", "description": "On-chain multisig withdrawal flow: fetch signing data, build a PSBT, and broadcast it once co-signed." } ], "x-tagGroups": [ { "name": "Authentication", "tags": [ "Authentication" ] }, { "name": "Wallet & Balances", "tags": [ "Wallet", "Multisig Withdrawal" ] }, { "name": "Payments & Merchants", "tags": [ "Payments" ] } ] }