{
"openapi": "3.1.0",
"info": {
"title": "barkd REST API",
"description": "A simple REST API for barkd, a wallet daemon for integrating bitcoin payments into your app over HTTP. Supports self-custodial Lightning, Ark, and on-chain out of the box.\n\nbarkd is a long-running daemon best suited for always-on or high-connectivity environments like nodes, servers, desktops, and point-of-sale terminals.\n\nAll endpoints return JSON. Amounts are denominated in satoshis.",
"contact": {
"name": "Second Team",
"email": "hello@second.tech"
},
"license": {
"name": "MIT",
"identifier": "MIT"
},
"version": "0.1.0"
},
"paths": {
"/api/v1/bitcoin/tip": {
"get": {
"tags": [
"bitcoin"
],
"summary": "Get bitcoin tip height",
"description": "Queries the wallet's chain source for the block height of the latest block on the best chain.",
"operationId": "tip",
"responses": {
"200": {
"description": "Returns the current bitcoin tip height",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TipResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/boards/": {
"get": {
"tags": [
"boards"
],
"summary": "List pending boards",
"description": "Returns all boards whose funding transactions have not yet reached the number of on-chain confirmations required by the Ark server.",
"operationId": "get_pending_boards",
"responses": {
"200": {
"description": "Returns all pending boards",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PendingBoardInfo"
}
}
}
}
},
"500": {
"description": "Internal server error"
}
}
}
},
"/api/v1/boards/board-all": {
"post": {
"tags": [
"boards"
],
"summary": "Board all on-chain bitcoin",
"description": "Moves all bitcoin in the on-chain wallet onto the Ark protocol. Creates and broadcasts a funding transaction that drains the on-chain balance into a single VTXO, then returns the pending board details. The resulting VTXO is not spendable off-chain until the funding transaction reaches the number of on-chain confirmations required by the Ark server.",
"operationId": "board_all",
"responses": {
"200": {
"description": "Returns the board result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PendingBoardInfo"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/boards/board-amount": {
"post": {
"tags": [
"boards"
],
"summary": "Board a specific amount",
"description": "Moves the specified amount of bitcoin in the on-chain wallet onto the Ark protocol. Creates and broadcasts a funding transaction, then returns the pending board details. The resulting VTXO is not spendable off-chain until the funding transaction reaches the number of on-chain confirmations required by the Ark server.",
"operationId": "board_amount",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BoardRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Returns the board result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PendingBoardInfo"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/exits/claim/all": {
"post": {
"tags": [
"exits"
],
"summary": "Claim all exited VTXOs",
"description": "Sweeps all claimable exit outputs into a single on-chain transaction sent to the specified address. Unlike `progress`, the daemon does not claim automatically—this endpoint must be called manually. Poll the `status` endpoint or call `progress` and check for `done: true` to know when VTXOs are ready to claim. This is the final step of the emergency exit process—the bitcoin is not considered back on-chain until this transaction confirms.",
"operationId": "exit_claim_all",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExitClaimAllRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Exit claimed successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExitClaimResponse"
}
}
}
},
"400": {
"description": "The provided destination address is invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/exits/claim/vtxos": {
"post": {
"tags": [
"exits"
],
"summary": "Claim specific exited VTXOs",
"description": "Sweeps the specified claimable exit outputs into a single on-chain transaction sent to the specified address. Unlike `progress`, the daemon does not claim automatically—this endpoint must be called manually. Poll the `status` endpoint or call `progress` and check for `done: true` to know when VTXOs are ready to claim. This is the final step of the emergency exit process—the bitcoin is not considered back on-chain until this transaction confirms.",
"operationId": "exit_claim_vtxos",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExitClaimVtxosRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Exit claimed successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExitClaimResponse"
}
}
}
},
"400": {
"description": "One of the provided VTXO isn't spendable, or the provided destination address is invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/exits/progress": {
"post": {
"tags": [
"exits"
],
"summary": "Progress exits",
"description": "Triggers all in-progress exits to advance by one step. The daemon already progresses exits automatically in the background—use this endpoint when you want immediate progress rather than waiting for the next automatic cycle. On each call, the endpoint checks whether previously broadcast transactions have confirmed and, if so, creates and broadcasts the next transaction in the sequence. The on-chain wallet must have sufficient bitcoin to cover transaction fees.",
"operationId": "exit_progress",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExitProgressRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Returns the exit progress",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExitProgressResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/exits/start/all": {
"post": {
"tags": [
"exits"
],
"summary": "Start exit for all VTXOs",
"description": "Registers all wallet VTXOs for emergency exit. The daemon automatically progresses registered exits in the background at the cadence defined by `SLOW_INTERVAL`, creating and broadcasting the required transactions in sequence. Once all exit transactions are confirmed and the timelock has elapsed, call `claim` to sweep the resulting outputs to an on-chain address.",
"operationId": "exit_start_all",
"responses": {
"200": {
"description": "Exit started successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExitStartResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/exits/start/vtxos": {
"post": {
"tags": [
"exits"
],
"summary": "Start exit for specific VTXOs",
"description": "Registers the specified VTXOs for emergency exit. The daemon automatically progresses registered exits in the background at the cadence defined by `SLOW_INTERVAL`, creating and broadcasting the required transactions in sequence. Once all exit transactions are confirmed and the timelock has elapsed, call `claim` to sweep the resulting outputs to an on-chain address.",
"operationId": "exit_start_vtxos",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExitStartRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Exit started successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExitStartResponse"
}
}
}
},
"400": {
"description": "No VTXO IDs provided, or one of the provided VTXO IDs is invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"404": {
"description": "One the VTXOs wasn't found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/exits/status": {
"get": {
"tags": [
"exits"
],
"summary": "List all exit statuses",
"description": "Returns the current state of every emergency exit in the wallet. Each entry includes which phase the exit is in (start, processing, awaiting-delta, claimable, claim-in-progress, or claimed), and optionally the full state transition history and the exit transaction packages with their CPFP children.",
"operationId": "get_all_exit_status",
"parameters": [
{
"name": "history",
"in": "query",
"description": "Whether to include the detailed history of the exit process",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "transactions",
"in": "query",
"description": "Whether to include the exit transactions and their CPFP children",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "Returns all exit statuses",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ExitTransactionStatus"
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/exits/status/{vtxo_id}": {
"get": {
"tags": [
"exits"
],
"summary": "Get exit status",
"description": "Returns the current state of an emergency exit for the specified VTXO, including which phase the exit is in (start, processing, awaiting-delta, claimable, claim-in-progress, or claimed). Optionally includes the full state transition history and the exit transaction packages with their CPFP children.",
"operationId": "get_exit_status_by_vtxo_id",
"parameters": [
{
"name": "vtxo_id",
"in": "path",
"description": "The VTXO to check the exit status of",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "history",
"in": "query",
"description": "Whether to include the detailed history of the exit process",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "transactions",
"in": "query",
"description": "Whether to include the exit transactions and their CPFP children",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "Returns the exit status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExitTransactionStatus"
}
}
}
},
"404": {
"description": "VTXO wasn't found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/fees/board": {
"get": {
"tags": [
"fees"
],
"summary": "Estimate board fee",
"description": "Estimates the Ark protocol fee for boarding the specified amount of on-chain bitcoin. The net amount is what the user receives as a VTXO. Does not include the on-chain transaction fee for the board anchor transaction.",
"operationId": "board_fee",
"parameters": [
{
"name": "amount_sat",
"in": "query",
"description": "The amount in satoshis to board",
"required": true,
"schema": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Returns the fee estimate",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FeeEstimateResponse"
}
}
}
},
"400": {
"description": "Invalid amount",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/fees/lightning/pay": {
"get": {
"tags": [
"fees"
],
"summary": "Estimate Lightning send fee",
"description": "Estimates the fee for sending the specified amount over Lightning. The net amount is what the recipient receives. The fee depends on the VTXOs selected and their expiry. If the wallet has insufficient funds, returns a worst-case fee estimate assuming the user acquires enough funds to cover the payment.",
"operationId": "lightning_send_fee",
"parameters": [
{
"name": "amount_sat",
"in": "query",
"description": "The amount in satoshis to send over Lightning",
"required": true,
"schema": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Returns the fee estimate",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FeeEstimateResponse"
}
}
}
},
"400": {
"description": "Invalid amount",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/fees/lightning/receive": {
"get": {
"tags": [
"fees"
],
"summary": "Estimate Lightning receive fee",
"description": "Estimates the fee for receiving the specified amount over Lightning. The gross amount is the Lightning payment amount, and the net amount is what the user receives as a VTXO after the Ark server deducts its fee.",
"operationId": "lightning_receive_fee",
"parameters": [
{
"name": "amount_sat",
"in": "query",
"description": "The amount in satoshis to receive over Lightning",
"required": true,
"schema": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Returns the fee estimate",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FeeEstimateResponse"
}
}
}
},
"400": {
"description": "Invalid amount",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/fees/offboard-all": {
"get": {
"tags": [
"fees"
],
"summary": "Estimate offboard-all fee",
"description": "Estimates the fee for offboarding the entire Ark balance to the given on-chain address. The gross amount is the total spendable balance, and the net amount is what the user receives on-chain after fees. The fee depends on the destination address type, current fee rates, and VTXO expiry.",
"operationId": "offboard_all_fee",
"parameters": [
{
"name": "address",
"in": "query",
"description": "The destination Bitcoin address",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Returns the fee estimate",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FeeEstimateResponse"
}
}
}
},
"400": {
"description": "Invalid address",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/fees/onchain": {
"get": {
"tags": [
"fees"
],
"summary": "Get on-chain fee rates",
"description": "Returns the current mempool fee rates from the chain source at three confirmation targets: fast (~1 block), regular (~3 blocks), and slow (~6 blocks). Rates are in sat/vB, rounded up.",
"operationId": "onchain_fee_rates",
"responses": {
"200": {
"description": "Returns current mempool fee rates",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OnchainFeeRatesResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/fees/send-onchain": {
"get": {
"tags": [
"fees"
],
"summary": "Estimate send-onchain fee",
"description": "Estimates the total fee for sending bitcoin from the Ark wallet to an on-chain address. The fee depends on the destination address type and current fee rates. The gross amount is what the user pays (including VTXOs spent), and the net amount is what the recipient receives on-chain.",
"operationId": "send_onchain_fee",
"parameters": [
{
"name": "amount_sat",
"in": "query",
"description": "The amount in satoshis to send on-chain",
"required": true,
"schema": {
"type": "integer",
"format": "int64",
"minimum": 0
}
},
{
"name": "address",
"in": "query",
"description": "The destination Bitcoin address",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Returns the fee estimate",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FeeEstimateResponse"
}
}
}
},
"400": {
"description": "Invalid amount or address",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/lightning/pay": {
"post": {
"tags": [
"lightning"
],
"summary": "Send a Lightning payment",
"description": "Sends a payment to a Lightning destination. Accepts a BOLT11 invoice, BOLT12 offer, or Lightning address. The `amount_sat` field is required for Lightning addresses but optional for invoices and offers. Comments are only supported for Lightning addresses.",
"operationId": "pay",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightningPayRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Returns success message, optionally with preimage if payment was immediately settled",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightningPayResponse"
}
}
}
},
"400": {
"description": "The provided destination is not a valid BOLT11 invoice, BOLT12 offer, or Lightning address",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/lightning/receives": {
"get": {
"tags": [
"lightning"
],
"summary": "List all pending receive statuses",
"description": "Returns the statuses of all pending Lightning receives, ordered from oldest to newest. A receive is pending until its `finished_at` timestamp is set, indicating it has settled or been canceled.",
"operationId": "list_receive_statuses",
"responses": {
"200": {
"description": "Returns all pending receive statuses",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LightningReceiveInfo"
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/lightning/receives/invoice": {
"post": {
"tags": [
"lightning"
],
"summary": "Create a BOLT11 invoice",
"description": "Generates a new BOLT11 invoice for the specified amount via the Ark server, creating a pending Lightning receive.",
"operationId": "generate_invoice",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightningInvoiceRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Returns the created invoice",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InvoiceInfo"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/lightning/receives/{identifier}": {
"get": {
"tags": [
"lightning"
],
"summary": "Get receive status",
"description": "Returns the status of a specified Lightning receive, identified by its payment hash, invoice string, or preimage. The response tracks progress through timestamps: `htlc_vtxos` is populated once HTLCs are created by the Ark server, `preimage_revealed_at` records when the preimage was sent, and `finished_at` indicates the receive has settled or been canceled.",
"operationId": "get_receive_status",
"parameters": [
{
"name": "identifier",
"in": "path",
"description": "Payment hash, invoice string or preimage to search for",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Returns the Lightning receive status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightningReceiveInfo"
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/onchain/addresses/next": {
"post": {
"tags": [
"onchain"
],
"summary": "Generate on-chain address",
"description": "Generates a new on-chain receiving address. Each call returns the next unused address from the wallet's HD keychain.",
"operationId": "onchain_address",
"responses": {
"200": {
"description": "Returns the on-chain address",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Address"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/onchain/balance": {
"get": {
"tags": [
"onchain"
],
"summary": "Get on-chain balance",
"description": "Returns the current on-chain wallet balance, broken down by confirmation status. The `trusted_spendable_sat` field is the sum of `confirmed_sat` and `trusted_pending_sat`—the balance that can be safely spent without risk of double-spend.",
"operationId": "onchain_balance",
"responses": {
"200": {
"description": "Returns the on-chain balance",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OnchainBalance"
}
}
}
}
}
}
},
"/api/v1/onchain/drain": {
"post": {
"tags": [
"onchain"
],
"summary": "Drain on-chain wallet",
"description": "Sends the entire on-chain wallet balance to the specified address. The recipient receives the full balance minus transaction fees. Broadcasts immediately at a fee rate targeting confirmation within three blocks and returns the transaction ID.",
"operationId": "onchain_drain",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OnchainDrainRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Returns the drain result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Send"
}
}
}
},
"400": {
"description": "The provided destination address is invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/onchain/send": {
"post": {
"tags": [
"onchain"
],
"summary": "Send on-chain payment",
"description": "Sends the specified amount to an on-chain address. Broadcasts the transaction immediately at a fee rate targeting confirmation within three blocks and returns the transaction ID.",
"operationId": "onchain_send",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OnchainSendRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Returns the send result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Send"
}
}
}
},
"400": {
"description": "The provided destination address is invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/onchain/send-many": {
"post": {
"tags": [
"onchain"
],
"summary": "Send to multiple addresses",
"description": "Batches multiple payments into a single on-chain transaction. Each destination is formatted as `address:amount`. Broadcasts the transaction immediately at a fee rate targeting confirmation within three blocks and returns the transaction ID.",
"operationId": "onchain_send_many",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OnchainSendManyRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Returns the send result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Send"
}
}
}
},
"400": {
"description": "One of the provided destinations is invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/onchain/sync": {
"post": {
"tags": [
"onchain"
],
"summary": "Sync on-chain wallet",
"description": "Syncs the on-chain wallet state with the chain source. Fetches new blocks and transactions, updates the UTXO set, and re-submits any stale unconfirmed transactions to the mempool.",
"operationId": "onchain_sync",
"responses": {
"200": {
"description": "Synced on-chain wallet"
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/onchain/transactions": {
"get": {
"tags": [
"onchain"
],
"summary": "List on-chain transactions",
"description": "Returns all on-chain wallet transactions, ordered from oldest to newest.",
"operationId": "onchain_transactions",
"responses": {
"200": {
"description": "Returns the on-chain transactions",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TransactionInfo"
}
}
}
}
}
}
}
},
"/api/v1/onchain/utxos": {
"get": {
"tags": [
"onchain"
],
"summary": "List on-chain UTXOs",
"description": "Returns all UTXOs in the on-chain wallet. Each entry includes the outpoint, amount, and confirmation height (if confirmed).",
"operationId": "onchain_utxos",
"responses": {
"200": {
"description": "Returns the on-chain UTXOs",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UtxoInfo"
}
}
}
}
}
}
}
},
"/api/v1/wallet": {
"get": {
"tags": [
"wallet"
],
"operationId": "wallet_exists",
"responses": {
"200": {
"description": "Wallet existence status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalletExistsResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
},
"delete": {
"tags": [
"wallet"
],
"operationId": "wallet_delete",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalletDeleteRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Wallet deletion status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalletDeleteResponse"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/addresses/index/{index}": {
"get": {
"tags": [
"wallet"
],
"summary": "Get Ark address by index",
"description": "Returns a previously generated Ark address by its derivation index. Only addresses that have already been generated are available.",
"operationId": "peek_address",
"parameters": [
{
"name": "index",
"in": "path",
"description": "Index for the address.",
"required": true,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Returns the Ark address",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ArkAddressResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/addresses/next": {
"post": {
"tags": [
"wallet"
],
"summary": "Generate Ark address",
"description": "Generates a new Ark receiving address. Each call returns the next unused address from the wallet's HD keychain.",
"operationId": "address",
"responses": {
"200": {
"description": "Returns the Ark address",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ArkAddressResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/ark-info": {
"get": {
"tags": [
"wallet"
],
"summary": "Get Ark server info",
"description": "Returns the Ark server's configuration parameters, including network, public key, round interval, VTXO expiry and exit deltas, fee settings, and Lightning support details.",
"operationId": "ark_info",
"responses": {
"200": {
"description": "Returns the Ark info",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ArkInfo"
}
}
}
},
"404": {
"description": "Wallet not connected to an Ark server",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/balance": {
"get": {
"tags": [
"wallet"
],
"summary": "Get wallet balance",
"description": "Returns the wallet balance broken down by category: spendable sats available for immediate use, sats pending in an Ark round, sats locked in outgoing or incoming Lightning payments, sats awaiting board confirmation, and sats in a pending exit. The balance is computed from local state, which the background daemon keeps reasonably fresh (Lightning syncs every second, mailbox and boards every 30 seconds). For the most up-to-date figures, call `sync` before this endpoint.",
"operationId": "balance",
"responses": {
"200": {
"description": "Returns the wallet balance",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Balance"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/connected": {
"get": {
"tags": [
"wallet"
],
"summary": "Check server connection",
"description": "Checks whether the wallet has an active connection to the Ark server. Returns `true` if the wallet can reach the server and retrieve its configuration, `false` otherwise. The background daemon checks the server connection every second, so this reflects the most recent known state.",
"operationId": "connected",
"responses": {
"200": {
"description": "Returns whether the wallet is connected to an Ark server",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConnectedResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/create": {
"post": {
"tags": [
"wallet"
],
"summary": "Create a wallet",
"description": "Creates a new wallet with the specified Ark server and chain source configuration. Fails if a wallet already exists. Returns the wallet fingerprint on success.",
"operationId": "create_wallet",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWalletRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Wallet created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWalletResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/history": {
"get": {
"tags": [
"wallet"
],
"summary": "Get wallet history",
"description": "Returns the full history of wallet movements ordered from newest to oldest. A movement represents any wallet operation that affects VTXOs—an arkoor send or receive, Lightning send or receive, board, offboard, or refresh. Each entry records which VTXOs were consumed and produced, the effective balance change (if any), fees paid, and the operation status.",
"operationId": "history",
"responses": {
"200": {
"description": "Returns the wallet history",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Movement"
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/import-vtxo": {
"post": {
"tags": [
"wallet"
],
"summary": "Import a VTXO",
"description": "Imports hex-encoded serialized VTXOs into the wallet. Validates that each VTXO is anchored on-chain, owned by this wallet, and has not expired. Useful for restoring VTXOs after database loss or re-importing from the server mailbox. The operation is idempotent.",
"operationId": "import_vtxo",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportVtxoRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "VTXO imported successfully",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WalletVtxoInfo"
}
}
}
}
},
"400": {
"description": "Invalid VTXO hex or VTXO not owned by wallet",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/movements": {
"get": {
"tags": [
"wallet"
],
"summary": "List movements (deprecated)",
"description": "Deprecated: Use history instead",
"operationId": "movements",
"responses": {
"200": {
"description": "Returns the wallet movements",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Movement"
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
},
"deprecated": true
}
},
"/api/v1/wallet/next-round": {
"get": {
"tags": [
"wallet"
],
"summary": "Get next round time",
"description": "Queries the Ark server for the next scheduled round start time and returns it in RFC 3339 format.",
"operationId": "next_round",
"responses": {
"200": {
"description": "Returns the next round start time",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NextRoundStart"
}
}
}
},
"404": {
"description": "Wallet not connected to an Ark server",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/offboard/all": {
"post": {
"tags": [
"wallet"
],
"summary": "Offboard all VTXOs",
"description": "Cooperatively moves all spendable VTXOs off the Ark protocol to an on-chain address. Each VTXO is offboarded in full—partial amounts are not supported. The on-chain transaction fee is deducted from the total, and the remaining amount is sent to the destination. If no address is specified, the wallet generates a new on-chain address. To send a specific amount on-chain, use `send-onchain` instead.",
"operationId": "offboard_all",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OffboardAllRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Returns the offboard transaction id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OffboardResult"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/offboard/vtxos": {
"post": {
"tags": [
"wallet"
],
"summary": "Offboard specific VTXOs",
"description": "Cooperatively moves the specified VTXOs off the Ark protocol to an on-chain address. Each VTXO is offboarded in full—partial amounts are not supported. The on-chain transaction fee is deducted from the total, and the remaining amount is sent to the destination. If no address is specified, the wallet generates a new on-chain address. To send a specific amount on-chain, use `send-onchain` instead.",
"operationId": "offboard_vtxos",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OffboardVtxosRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Returns the offboard transaction id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OffboardResult"
}
}
}
},
"400": {
"description": "No VTXO IDs provided, or one of the provided VTXO IDs is invalid, or destination address is invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"404": {
"description": "One the VTXOs wasn't found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundError"
}
}
}
},
"500": {
"description": "Internal server error"
}
}
}
},
"/api/v1/wallet/refresh/all": {
"post": {
"tags": [
"wallet"
],
"summary": "Refresh all VTXOs",
"description": "Registers all spendable VTXOs for refresh in the next Ark round. The input VTXOs are locked immediately and will be forfeited once the round completes, yielding new VTXOs with a fresh expiry. The background daemon automatically participates in the round and progresses it to completion. Use the `rounds` endpoint to track progress.",
"operationId": "refresh_all",
"responses": {
"200": {
"description": "Returns the refresh result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PendingRoundInfo"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/refresh/counterparty": {
"post": {
"tags": [
"wallet"
],
"summary": "Refresh received VTXOs",
"description": "Registers all out-of-round VTXOs held by the wallet for refresh in the next Ark round. Refreshing replaces out-of-round VTXOs under arkoor trust assumptions with trustless, in-round VTXOs. Out-of-round VTXOs whose entire transaction chain originates from your own in-round VTXOs are excluded. The background daemon automatically participates in the round and progresses it to completion. Use the `rounds` endpoint to track progress.",
"operationId": "refresh_counterparty",
"responses": {
"200": {
"description": "Returns the refresh result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PendingRoundInfo"
}
}
}
},
"404": {
"description": "There is no VTXO to refresh",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/refresh/vtxos": {
"post": {
"tags": [
"wallet"
],
"summary": "Refresh specific VTXOs",
"description": "Registers the specified VTXOs for refresh in the next Ark round. The input VTXOs are locked immediately and will be forfeited once the round completes, yielding new VTXOs with a fresh expiry. The background daemon automatically participates in the round and progresses it to completion. Use the `rounds` endpoint to track progress.",
"operationId": "refresh_vtxos",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RefreshRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Returns the refresh result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PendingRoundInfo"
}
}
}
},
"400": {
"description": "No VTXO IDs provided, or one of the provided VTXO IDs is invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"404": {
"description": "One the VTXOs wasn't found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/rounds": {
"get": {
"tags": [
"wallet"
],
"summary": "List round participations",
"description": "Returns all active round participations and their current status. A round participation is created when you call one of the `refresh` endpoints and persists until the round's funding transaction is confirmed on-chain (2 confirmations on mainnet, 1 on testnet). The list can contain multiple entries—for example, a previous round awaiting on-chain confirmation alongside a newly submitted round waiting for the next server round to start. Confirmed and failed rounds are removed automatically by the background daemon.",
"operationId": "pending_rounds",
"responses": {
"200": {
"description": "Returns the wallet pending rounds",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PendingRoundInfo"
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/send": {
"post": {
"tags": [
"wallet"
],
"summary": "Send a payment",
"description": "Sends an Ark or Lightning payment to the specified destination. Accepts an Ark address, BOLT11 invoice, BOLT12 offer, or Lightning address. Ark address payments are settled instantly via an out-of-round (arkoor) transaction. The `amount_sat` field is required for Ark addresses and Lightning addresses but optional for invoices and offers that already encode an amount. Comments are only supported for Lightning addresses. To send to an on-chain bitcoin address, use `send-onchain` instead.",
"operationId": "send",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SendRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Payment sent successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SendResponse"
}
}
}
},
"400": {
"description": "The provided destination is not a valid Ark address, BOLT11 invoice, BOLT12 offer, or Lightning address",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/send-onchain": {
"post": {
"tags": [
"wallet"
],
"summary": "Send on-chain from Ark balance",
"description": "Sends the specified amount to an on-chain address using the wallet's off-chain Ark balance. The on-chain transaction fee is paid on top of the specified amount. Internally creates an out-of-round transaction to consolidate VTXOs into the exact amount needed, then cooperatively sends the on-chain payment via the Ark server. To offboard entire VTXOs without specifying an amount, use `offboard/vtxos` or `offboard/all` instead.",
"operationId": "send_onchain",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SendOnchainRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Returns the offboard transaction id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OffboardResult"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/sync": {
"post": {
"tags": [
"wallet"
],
"summary": "Sync wallet",
"description": "Triggers an immediate sync of the wallet's off-chain state. Updates on-chain fee rates, processes incoming arkoor payments, resolves outgoing and incoming Lightning payments, and progresses pending rounds and boards toward confirmation. The background daemon already runs these operations automatically (e.g., Lightning every second, mailbox and boards every 30 seconds), but calling `sync` forces all of them to run immediately.",
"operationId": "sync",
"responses": {
"200": {
"description": "Wallet was successfully synced"
}
}
}
},
"/api/v1/wallet/vtxos": {
"get": {
"tags": [
"wallet"
],
"summary": "List VTXOs",
"description": "Returns VTXOs held by the wallet, including their state and expiry information. By default returns only non-spent VTXOs. Set `all=true` to include all VTXOs regardless of state.",
"operationId": "vtxos",
"parameters": [
{
"name": "all",
"in": "query",
"description": "Return all VTXOs regardless of their state. If not provided, returns only non-spent VTXOs.",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "Returns the wallet VTXOs",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WalletVtxoInfo"
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/vtxos/{id}": {
"get": {
"tags": [
"wallet"
],
"summary": "Get VTXO detail",
"description": "Returns detail for a single VTXO. To get the hex-encoded serialization use `GET /vtxos/{id}/encoded`.",
"operationId": "get_vtxo",
"parameters": [
{
"name": "id",
"in": "path",
"description": "VTXO identifier formatted as `txid:vout`.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Returns the VTXO detail",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalletVtxoInfo"
}
}
}
},
"400": {
"description": "Invalid VTXO id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"404": {
"description": "VTXO not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/api/v1/wallet/vtxos/{id}/encoded": {
"get": {
"tags": [
"wallet"
],
"summary": "Get encoded VTXO",
"description": "Returns the hex-encoded serialization of a VTXO. The `encoded` field can be passed to `POST /wallet/import-vtxo` to re-import this VTXO.",
"operationId": "get_vtxo_encoded",
"parameters": [
{
"name": "id",
"in": "path",
"description": "VTXO identifier formatted as `txid:vout`.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Returns the hex-encoded serialized VTXO",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EncodedVtxoResponse"
}
}
}
},
"400": {
"description": "Invalid VTXO id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"404": {
"description": "VTXO not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundError"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerError"
}
}
}
}
}
}
},
"/ping": {
"get": {
"tags": [],
"summary": "Ping",
"operationId": "ping",
"responses": {
"200": {
"description": "Returns pong"
}
},
"security": [
{}
]
}
}
},
"components": {
"schemas": {
"Address": {
"type": "object",
"required": [
"address"
],
"properties": {
"address": {
"type": "string"
}
}
},
"ArkAddressResponse": {
"type": "object",
"required": [
"address"
],
"properties": {
"address": {
"type": "string"
}
}
},
"ArkInfo": {
"type": "object",
"required": [
"network",
"server_pubkey",
"mailbox_pubkey",
"round_interval",
"nb_round_nonces",
"vtxo_exit_delta",
"vtxo_expiry_delta",
"htlc_send_expiry_delta",
"htlc_expiry_delta",
"max_vtxo_amount",
"required_board_confirmations",
"max_user_invoice_cltv_delta",
"min_board_amount_sat",
"offboard_feerate_sat_per_kvb",
"ln_receive_anti_dos_required",
"fees"
],
"properties": {
"fees": {
"$ref": "#/components/schemas/FeeSchedule",
"description": "The fee schedule outlining any fees that must be paid to interact with the Ark server."
},
"htlc_expiry_delta": {
"$ref": "#/components/schemas/u16",
"description": "The number of blocks to keep between Lightning and Ark HTLCs expiries"
},
"htlc_send_expiry_delta": {
"$ref": "#/components/schemas/u16",
"description": "The number of blocks after which an HTLC-send VTXO expires once granted."
},
"ln_receive_anti_dos_required": {
"type": "boolean",
"description": "Indicates whether the Ark server requires clients to either\nprovide a VTXO ownership proof, or a lightning receive token\nwhen preparing a lightning claim."
},
"mailbox_pubkey": {
"type": "string",
"description": "The pubkey used for blinding unified mailbox IDs"
},
"max_user_invoice_cltv_delta": {
"type": "integer",
"format": "int32",
"description": "Maximum CLTV delta server will allow clients to request an\ninvoice generation with.",
"minimum": 0
},
"max_vtxo_amount": {
"type": "integer",
"format": "int64",
"description": "Maximum amount of a VTXO",
"minimum": 0
},
"min_board_amount_sat": {
"type": "integer",
"format": "int64",
"description": "Minimum amount for a board the server will cosign",
"minimum": 0
},
"nb_round_nonces": {
"type": "integer",
"description": "Number of nonces per round",
"minimum": 0
},
"network": {
"type": "string",
"description": "The bitcoin network the server operates on"
},
"offboard_feerate_sat_per_kvb": {
"type": "integer",
"format": "int64",
"description": "offboard feerate in sat per kvb",
"minimum": 0
},
"required_board_confirmations": {
"type": "integer",
"description": "The number of confirmations required to register a board vtxo",
"minimum": 0
},
"round_interval": {
"type": "string",
"description": "The interval between each round"
},
"server_pubkey": {
"type": "string",
"description": "The Ark server pubkey"
},
"vtxo_exit_delta": {
"$ref": "#/components/schemas/u16",
"description": "Delta between exit confirmation and coins becoming spendable"
},
"vtxo_expiry_delta": {
"$ref": "#/components/schemas/u16",
"description": "Expiration delta of the VTXO"
}
}
},
"BadRequestError": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string"
}
}
},
"Balance": {
"type": "object",
"description": "The different balances of a Bark wallet, broken down by state.\n\nAll amounts are in sats.",
"required": [
"spendable_sat",
"pending_lightning_send_sat",
"claimable_lightning_receive_sat",
"pending_in_round_sat",
"pending_board_sat"
],
"properties": {
"claimable_lightning_receive_sat": {
"type": "integer",
"format": "int64",
"description": "Sats from an incoming Lightning payment that can be claimed but\nhave not yet been swept into a spendable VTXO.",
"minimum": 0
},
"pending_board_sat": {
"type": "integer",
"format": "int64",
"description": "Sats in board transactions that are waiting for sufficient\non-chain confirmations before becoming spendable.",
"minimum": 0
},
"pending_exit_sat": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Sats in VTXOs undergoing an emergency exit back on-chain.\n`null` if the exit subsystem is unavailable.",
"minimum": 0
},
"pending_in_round_sat": {
"type": "integer",
"format": "int64",
"description": "Sats locked in VTXOs forfeited for a round that has not yet\ncompleted.",
"minimum": 0
},
"pending_lightning_send_sat": {
"type": "integer",
"format": "int64",
"description": "Sats locked in an outgoing Lightning payment that has not yet\nsettled.",
"minimum": 0
},
"spendable_sat": {
"type": "integer",
"format": "int64",
"description": "Sats that are immediately spendable, either in-round or\nout-of-round.",
"minimum": 0
}
}
},
"BarkNetwork": {
"type": "string",
"description": "Networks bark can be used on",
"enum": [
"mainnet",
"signet",
"mutinynet",
"regtest"
]
},
"BitcoindAuth": {
"oneOf": [
{
"type": "object",
"description": "Use a cookie file for authentication",
"required": [
"cookie"
],
"properties": {
"cookie": {
"type": "object",
"description": "Use a cookie file for authentication",
"required": [
"cookie"
],
"properties": {
"cookie": {
"type": "string"
}
}
}
}
},
{
"type": "object",
"description": "Use a username and password for authentication",
"required": [
"user-pass"
],
"properties": {
"user-pass": {
"type": "object",
"description": "Use a username and password for authentication",
"required": [
"user",
"pass"
],
"properties": {
"pass": {
"type": "string"
},
"user": {
"type": "string"
}
}
}
}
}
]
},
"BlockRef": {
"type": "object",
"description": "Reference to a block in the blockchain.\n\nContains the block height and hash. Serializes as an object with `height` and `hash` fields.",
"required": [
"height",
"hash"
],
"properties": {
"hash": {
"type": "string"
},
"height": {
"$ref": "#/components/schemas/u32"
}
}
},
"BoardFees": {
"type": "object",
"description": "Fees for boarding the ark.",
"required": [
"min_fee_sat",
"base_fee_sat",
"ppm"
],
"properties": {
"base_fee_sat": {
"type": "integer",
"format": "int64",
"description": "A fee applied to every transaction regardless of value.",
"minimum": 0
},
"min_fee_sat": {
"type": "integer",
"format": "int64",
"description": "Minimum fee to charge.",
"minimum": 0
},
"ppm": {
"type": "integer",
"format": "int64",
"description": "PPM (parts per million) fee rate to apply based on the value of the transaction.",
"minimum": 0
}
}
},
"BoardRequest": {
"type": "object",
"required": [
"amount_sat"
],
"properties": {
"amount_sat": {
"type": "integer",
"format": "int64",
"description": "An amount of onchain funds to board (in satoshis). For a board operation to be successful,\nthis value, with any server-configured [BoardFees](crate::cli::BoardFees) deducted, must be\n>= [P2TR_DUST](bitcoin_ext::P2TR_DUST).",
"minimum": 0
}
}
},
"ChainSourceConfig": {
"oneOf": [
{
"type": "object",
"description": "Use a bitcoind RPC server",
"required": [
"bitcoind"
],
"properties": {
"bitcoind": {
"type": "object",
"description": "Use a bitcoind RPC server",
"required": [
"bitcoind",
"bitcoind_auth"
],
"properties": {
"bitcoind": {
"type": "string"
},
"bitcoind_auth": {
"$ref": "#/components/schemas/BitcoindAuth"
}
}
}
}
},
{
"type": "object",
"description": "Use an Esplora HTTP server",
"required": [
"esplora"
],
"properties": {
"esplora": {
"type": "object",
"description": "Use an Esplora HTTP server",
"required": [
"url"
],
"properties": {
"url": {
"type": "string"
}
}
}
}
}
]
},
"ChildTransactionInfo": {
"type": "object",
"description": "Represents a child transaction for an exit transaction package with information about the origin\nof the transaction",
"required": [
"info",
"origin"
],
"properties": {
"info": {
"$ref": "#/components/schemas/TransactionInfo"
},
"origin": {
"$ref": "#/components/schemas/ExitTxOrigin"
}
}
},
"ConnectedResponse": {
"type": "object",
"required": [
"connected"
],
"properties": {
"connected": {
"type": "boolean",
"description": "Whether the wallet is currently connected to its Ark server"
}
}
},
"CreateWalletRequest": {
"type": "object",
"required": [
"ark_server",
"chain_source",
"network"
],
"properties": {
"ark_server": {
"type": "string",
"description": "The Ark server to use for the wallet"
},
"birthday_height": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "An optional birthday height to start syncing the wallet from",
"minimum": 0
},
"chain_source": {
"$ref": "#/components/schemas/ChainSourceConfig",
"description": "The chain source to use for the wallet"
},
"mnemonic": {
"type": [
"string",
"null"
],
"description": "The optional mnemonic to use for the wallet"
},
"network": {
"$ref": "#/components/schemas/BarkNetwork",
"description": "The network to use for the wallet"
}
}
},
"CreateWalletResponse": {
"type": "object",
"required": [
"fingerprint"
],
"properties": {
"fingerprint": {
"type": "string"
}
}
},
"EncodedVtxo": {
"type": "string",
"description": "Hex-encoded serialized VTXO.\n\nSerializes as a plain hex string. Can be passed to\n`POST /wallet/import-vtxo` to re-import this VTXO."
},
"EncodedVtxoResponse": {
"type": "object",
"description": "Response for the encoded-VTXO endpoint.\n\nWraps the hex-encoded VTXO in a named field so clients can easily\nextract it.",
"required": [
"encoded"
],
"properties": {
"encoded": {
"$ref": "#/components/schemas/EncodedVtxo",
"description": "Hex-encoded serialized VTXO."
}
}
},
"ExitAwaitingDeltaState": {
"type": "object",
"required": [
"tip_height",
"confirmed_block",
"claimable_height"
],
"properties": {
"claimable_height": {
"$ref": "#/components/schemas/u32"
},
"confirmed_block": {
"$ref": "#/components/schemas/BlockRef"
},
"tip_height": {
"$ref": "#/components/schemas/u32"
}
}
},
"ExitClaimAllRequest": {
"type": "object",
"required": [
"destination"
],
"properties": {
"destination": {
"type": "string",
"description": "The destination Bitcoin address"
},
"fee_rate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Sets the desired fee-rate in sats/kvB to use broadcasting exit transactions",
"minimum": 0
}
}
},
"ExitClaimInProgressState": {
"type": "object",
"required": [
"tip_height",
"claimable_since",
"claim_txid"
],
"properties": {
"claim_txid": {
"type": "string"
},
"claimable_since": {
"$ref": "#/components/schemas/BlockRef"
},
"tip_height": {
"$ref": "#/components/schemas/u32"
}
}
},
"ExitClaimResponse": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string"
}
}
},
"ExitClaimVtxosRequest": {
"type": "object",
"required": [
"destination",
"vtxos"
],
"properties": {
"destination": {
"type": "string",
"description": "The destination Bitcoin address"
},
"fee_rate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Sets the desired fee-rate in sats/kvB to use broadcasting exit transactions",
"minimum": 0
},
"vtxos": {
"type": "array",
"items": {
"type": "string"
},
"description": "The ID of an exited VTXO to be claimed"
}
}
},
"ExitClaimableState": {
"type": "object",
"required": [
"tip_height",
"claimable_since"
],
"properties": {
"claimable_since": {
"$ref": "#/components/schemas/BlockRef"
},
"last_scanned_block": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/BlockRef"
}
]
},
"tip_height": {
"$ref": "#/components/schemas/u32"
}
}
},
"ExitClaimedState": {
"type": "object",
"required": [
"tip_height",
"txid",
"block"
],
"properties": {
"block": {
"$ref": "#/components/schemas/BlockRef"
},
"tip_height": {
"$ref": "#/components/schemas/u32"
},
"txid": {
"type": "string"
}
}
},
"ExitError": {
"oneOf": [
{
"type": "object",
"required": [
"txid",
"error",
"type"
],
"properties": {
"error": {
"type": "string"
},
"txid": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"ancestor-retrieval-failure"
]
}
}
},
{
"type": "object",
"required": [
"height",
"error",
"type"
],
"properties": {
"error": {
"type": "string"
},
"height": {
"$ref": "#/components/schemas/u32"
},
"type": {
"type": "string",
"enum": [
"block-retrieval-failure"
]
}
}
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"claim-missing-inputs"
]
}
}
},
{
"type": "object",
"required": [
"needed",
"output",
"type"
],
"properties": {
"needed": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"output": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"type": {
"type": "string",
"enum": [
"claim-fee-exceeds-output"
]
}
}
},
{
"type": "object",
"required": [
"vtxo",
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"claim-missing-signable-clause"
]
},
"vtxo": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"error",
"type"
],
"properties": {
"error": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"claim-signing-error"
]
}
}
},
{
"type": "object",
"required": [
"vtxo",
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"cyclic-exit-transactions"
]
},
"vtxo": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"vtxo_id",
"error",
"type"
],
"properties": {
"error": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"database-vtxo-store-failure"
]
},
"vtxo_id": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"error",
"type"
],
"properties": {
"error": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"database-child-retrieval-failure"
]
}
}
},
{
"type": "object",
"required": [
"vtxo",
"dust",
"type"
],
"properties": {
"dust": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"type": {
"type": "string",
"enum": [
"dust-limit"
]
},
"vtxo": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
},
{
"type": "object",
"required": [
"txid",
"error",
"type"
],
"properties": {
"error": {
"type": "string"
},
"txid": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"exit-package-broadcast-failure"
]
}
}
},
{
"type": "object",
"required": [
"error",
"type"
],
"properties": {
"error": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"exit-package-finalize-failure"
]
}
}
},
{
"type": "object",
"required": [
"txid",
"error",
"type"
],
"properties": {
"error": {
"type": "string"
},
"txid": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"exit-package-store-failure"
]
}
}
},
{
"type": "object",
"required": [
"needed",
"available",
"type"
],
"properties": {
"available": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"needed": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"type": {
"type": "string",
"enum": [
"insufficient-confirmed-funds"
]
}
}
},
{
"type": "object",
"required": [
"balance",
"total_fee",
"fee_rate_sat_per_kvb",
"fee_rate_kwu",
"type"
],
"properties": {
"balance": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"fee_rate_kwu": {
"type": "integer",
"format": "int64",
"deprecated": true,
"minimum": 0
},
"fee_rate_sat_per_kvb": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"total_fee": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"type": {
"type": "string",
"enum": [
"insufficient-fee-to-start"
]
}
}
},
{
"type": "object",
"required": [
"error",
"type"
],
"properties": {
"error": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"internal-error"
]
}
}
},
{
"type": "object",
"required": [
"txid",
"status",
"error",
"type"
],
"properties": {
"error": {
"type": "string"
},
"status": {
"$ref": "#/components/schemas/ExitTxStatus"
},
"txid": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"invalid-exit-transaction-status"
]
}
}
},
{
"type": "object",
"required": [
"tip",
"error",
"type"
],
"properties": {
"error": {
"type": "string"
},
"tip": {
"$ref": "#/components/schemas/u32"
},
"type": {
"type": "string",
"enum": [
"invalid-locktime"
]
}
}
},
{
"type": "object",
"required": [
"error",
"type"
],
"properties": {
"error": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"invalid-wallet-state"
]
}
}
},
{
"type": "object",
"required": [
"txid",
"type"
],
"properties": {
"txid": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"missing-anchor-output"
]
}
}
},
{
"type": "object",
"required": [
"txid",
"type"
],
"properties": {
"txid": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"missing-exit-transaction"
]
}
}
},
{
"type": "object",
"required": [
"error",
"type"
],
"properties": {
"error": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"movement-registration-failure"
]
}
}
},
{
"type": "object",
"required": [
"error",
"type"
],
"properties": {
"error": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"tip-retrieval-failure"
]
}
}
},
{
"type": "object",
"required": [
"txid",
"error",
"type"
],
"properties": {
"error": {
"type": "string"
},
"txid": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"transaction-retrieval-failure"
]
}
}
},
{
"type": "object",
"required": [
"vtxo",
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"vtxo-not-claimable"
]
},
"vtxo": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"error",
"type"
],
"properties": {
"error": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"vtxo-script-pub-key-invalid"
]
}
}
}
]
},
"ExitProcessingState": {
"type": "object",
"required": [
"tip_height",
"transactions"
],
"properties": {
"tip_height": {
"$ref": "#/components/schemas/u32"
},
"transactions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ExitTx"
}
}
}
},
"ExitProgressRequest": {
"type": "object",
"properties": {
"fee_rate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Sets the desired fee-rate in sats/kvB to use broadcasting exit transactions",
"minimum": 0
},
"wait": {
"type": [
"boolean",
"null"
],
"description": "Wait until the exit is completed"
}
}
},
"ExitProgressResponse": {
"type": "object",
"required": [
"exits",
"done"
],
"properties": {
"claimable_height": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Block height at which all exit outputs will be spendable",
"minimum": 0
},
"done": {
"type": "boolean",
"description": "Whether all transactions have been confirmed"
},
"exits": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ExitProgressStatus"
},
"description": "Status of each pending exit transaction"
}
}
},
"ExitProgressStatus": {
"type": "object",
"required": [
"vtxo_id",
"state"
],
"properties": {
"error": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ExitError",
"description": "Any error that occurred during the exit process"
}
]
},
"state": {
"$ref": "#/components/schemas/ExitState",
"description": "The current state of the exit transaction"
},
"vtxo_id": {
"type": "string",
"description": "The ID of the VTXO that is being unilaterally exited"
}
}
},
"ExitStartRequest": {
"type": "object",
"required": [
"vtxos"
],
"properties": {
"vtxos": {
"type": "array",
"items": {
"type": "string"
},
"description": "The ID of VTXOs to unilaterally exit"
}
}
},
"ExitStartResponse": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string"
}
}
},
"ExitStartState": {
"type": "object",
"required": [
"tip_height"
],
"properties": {
"tip_height": {
"$ref": "#/components/schemas/u32"
}
}
},
"ExitState": {
"oneOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/ExitStartState"
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"start"
]
}
}
}
]
},
{
"allOf": [
{
"$ref": "#/components/schemas/ExitProcessingState"
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"processing"
]
}
}
}
]
},
{
"allOf": [
{
"$ref": "#/components/schemas/ExitAwaitingDeltaState"
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"awaiting-delta"
]
}
}
}
]
},
{
"allOf": [
{
"$ref": "#/components/schemas/ExitClaimableState"
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"claimable"
]
}
}
}
]
},
{
"allOf": [
{
"$ref": "#/components/schemas/ExitClaimInProgressState"
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"claim-in-progress"
]
}
}
}
]
},
{
"allOf": [
{
"$ref": "#/components/schemas/ExitClaimedState"
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"claimed"
]
}
}
}
]
}
],
"description": "A utility type to wrap ExitState children so they can be easily serialized. This also helps with\ndebugging a lot!"
},
"ExitStatusRequest": {
"type": "object",
"properties": {
"history": {
"type": [
"boolean",
"null"
],
"description": "Whether to include the detailed history of the exit process"
},
"transactions": {
"type": [
"boolean",
"null"
],
"description": "Whether to include the exit transactions and their CPFP children"
}
}
},
"ExitTransactionPackage": {
"type": "object",
"required": [
"exit"
],
"properties": {
"child": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ChildTransactionInfo",
"description": "The child transaction used to spend, and thus confirm, the exit anchor output"
}
]
},
"exit": {
"$ref": "#/components/schemas/TransactionInfo",
"description": "The actual unilateral exit transaction containing an anchor output and a spendable amount"
}
}
},
"ExitTransactionStatus": {
"type": "object",
"required": [
"vtxo_id",
"state"
],
"properties": {
"history": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/ExitState"
},
"description": "The history of each state the exit transaction has gone through"
},
"state": {
"$ref": "#/components/schemas/ExitState",
"description": "The current state of the exit transaction"
},
"transactions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ExitTransactionPackage"
},
"description": "Each exit transaction package required for the unilateral exit"
},
"vtxo_id": {
"type": "string",
"description": "The ID of the VTXO that is being unilaterally exited"
}
}
},
"ExitTx": {
"type": "object",
"required": [
"txid",
"status"
],
"properties": {
"status": {
"$ref": "#/components/schemas/ExitTxStatus"
},
"txid": {
"type": "string"
}
}
},
"ExitTxOrigin": {
"oneOf": [
{
"type": "object",
"required": [
"type"
],
"properties": {
"confirmed_in": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/BlockRef"
}
]
},
"type": {
"type": "string",
"enum": [
"wallet"
]
}
}
},
{
"type": "object",
"required": [
"fee_rate_sat_per_kvb",
"fee_rate",
"total_fee",
"type"
],
"properties": {
"fee_rate": {
"type": "integer",
"format": "int64",
"deprecated": true,
"minimum": 0
},
"fee_rate_sat_per_kvb": {
"type": "integer",
"format": "int64",
"description": "This is the effective fee rate of the transaction (including CPFP ancestors)",
"minimum": 0
},
"total_fee": {
"type": "integer",
"format": "int64",
"description": "This includes the fees of the CPFP ancestors",
"minimum": 0
},
"type": {
"type": "string",
"enum": [
"mempool"
]
}
}
},
{
"type": "object",
"required": [
"confirmed_in",
"type"
],
"properties": {
"confirmed_in": {
"$ref": "#/components/schemas/BlockRef"
},
"type": {
"type": "string",
"enum": [
"block"
]
}
}
}
]
},
"ExitTxStatus": {
"oneOf": [
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"verify-inputs"
]
}
}
},
{
"type": "object",
"required": [
"txids",
"type"
],
"properties": {
"txids": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "string",
"enum": [
"awaiting-input-confirmation"
]
}
}
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"needs-signed-package"
]
}
}
},
{
"type": "object",
"required": [
"min_fee_rate_sat_per_kvb",
"min_fee_rate_kwu",
"min_fee",
"type"
],
"properties": {
"min_fee": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"min_fee_rate_kwu": {
"type": "integer",
"format": "int64",
"deprecated": true,
"minimum": 0
},
"min_fee_rate_sat_per_kvb": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"type": {
"type": "string",
"enum": [
"needs-replacement-package"
]
}
}
},
{
"type": "object",
"required": [
"child_txid",
"origin",
"type"
],
"properties": {
"child_txid": {
"type": "string"
},
"origin": {
"$ref": "#/components/schemas/ExitTxOrigin"
},
"type": {
"type": "string",
"enum": [
"needs-broadcasting"
]
}
}
},
{
"type": "object",
"required": [
"child_txid",
"origin",
"type"
],
"properties": {
"child_txid": {
"type": "string"
},
"origin": {
"$ref": "#/components/schemas/ExitTxOrigin"
},
"type": {
"type": "string",
"enum": [
"broadcast-with-cpfp"
]
}
}
},
{
"type": "object",
"required": [
"child_txid",
"block",
"origin",
"type"
],
"properties": {
"block": {
"$ref": "#/components/schemas/BlockRef"
},
"child_txid": {
"type": "string"
},
"origin": {
"$ref": "#/components/schemas/ExitTxOrigin"
},
"type": {
"type": "string",
"enum": [
"confirmed"
]
}
}
}
]
},
"FeeEstimateQuery": {
"type": "object",
"description": "Query parameters for fee estimates that only require an amount.",
"required": [
"amount_sat"
],
"properties": {
"amount_sat": {
"type": "integer",
"format": "int64",
"description": "The amount in satoshis to estimate fees for",
"minimum": 0
}
}
},
"FeeEstimateResponse": {
"type": "object",
"description": "A fee estimate for an Ark wallet operation.",
"required": [
"gross_amount_sat",
"fee_sat",
"net_amount_sat",
"vtxos_spent"
],
"properties": {
"fee_sat": {
"type": "integer",
"format": "int64",
"description": "The fee portion (in satoshis)",
"minimum": 0
},
"gross_amount_sat": {
"type": "integer",
"format": "int64",
"description": "The total amount including fees (in satoshis)",
"minimum": 0
},
"net_amount_sat": {
"type": "integer",
"format": "int64",
"description": "The amount excluding fees (in satoshis). For sends, this is the amount\nthe recipient receives. For receives, this is the amount the user gets.",
"minimum": 0
},
"vtxos_spent": {
"type": "array",
"items": {
"type": "string"
},
"description": "The VTXOs that would be spent for this operation"
}
}
},
"FeeSchedule": {
"type": "object",
"description": "Complete fee schedule for all operations.",
"required": [
"board",
"offboard",
"refresh",
"lightning_receive",
"lightning_send"
],
"properties": {
"board": {
"$ref": "#/components/schemas/BoardFees"
},
"lightning_receive": {
"$ref": "#/components/schemas/LightningReceiveFees"
},
"lightning_send": {
"$ref": "#/components/schemas/LightningSendFees"
},
"offboard": {
"$ref": "#/components/schemas/OffboardFees"
},
"refresh": {
"$ref": "#/components/schemas/RefreshFees"
}
}
},
"ImportVtxoRequest": {
"type": "object",
"required": [
"vtxos"
],
"properties": {
"vtxos": {
"type": "array",
"items": {
"type": "string"
},
"description": "Hex-encoded VTXOs to import"
}
}
},
"InternalServerError": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string"
}
}
},
"InvoiceInfo": {
"type": "object",
"required": [
"invoice"
],
"properties": {
"invoice": {
"type": "string",
"description": "The invoice string"
}
}
},
"LightningInvoiceRequest": {
"type": "object",
"required": [
"amount_sat"
],
"properties": {
"amount_sat": {
"type": "integer",
"format": "int64",
"description": "The amount to create invoice for (in satoshis). This is the amount the payee will pay but\nthe final amount received by the client will have any server-configured\n[LightningReceiveFees](crate::cli::LightningReceiveFees) deducted.",
"minimum": 0
}
}
},
"LightningPayRequest": {
"type": "object",
"required": [
"destination"
],
"properties": {
"amount_sat": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The amount to send (in satoshis). Optional for bolt11 invoices with amount. This must be\nhigher than the minimum fee laid out in server-configured\n[LightningSendFees](crate::cli::LightningSendFees). The wallet must also contain enough\nfunds to cover the amount plus any fees.",
"minimum": 0
},
"comment": {
"type": [
"string",
"null"
],
"description": "An optional comment, only supported when paying to lightning addresses"
},
"destination": {
"type": "string",
"description": "The invoice, offer, or lightning address to pay"
}
}
},
"LightningPayResponse": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"description": "Success message"
}
}
},
"LightningReceiveFees": {
"type": "object",
"description": "Fees for lightning receive operations.",
"required": [
"base_fee_sat",
"ppm"
],
"properties": {
"base_fee_sat": {
"type": "integer",
"format": "int64",
"description": "A fee applied to every transaction regardless of value.",
"minimum": 0
},
"ppm": {
"type": "integer",
"format": "int64",
"description": "PPM (parts per million) fee rate to apply based on the value of the transaction.",
"minimum": 0
}
}
},
"LightningReceiveInfo": {
"type": "object",
"required": [
"amount_sat",
"payment_hash",
"payment_preimage",
"invoice",
"htlc_vtxos"
],
"properties": {
"amount_sat": {
"type": "integer",
"format": "int64",
"description": "The amount of the lightning receive",
"minimum": 0
},
"finished_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "The timestamp at which the lightning receive was finished"
},
"htlc_vtxos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WalletVtxoInfo"
},
"description": "The HTLC VTXOs granted by the server for the lightning receive\n\nEmpty if the lightning HTLC has not yet been received by the server."
},
"invoice": {
"type": "string",
"description": "The invoice string"
},
"payment_hash": {
"type": "string",
"description": "The payment hash linked to the lightning receive info"
},
"payment_preimage": {
"type": "string",
"description": "The payment preimage linked to the lightning receive info"
},
"preimage_revealed_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "The timestamp at which the preimage was revealed"
}
}
},
"LightningSendFees": {
"type": "object",
"description": "Fees for lightning send operations.",
"required": [
"min_fee_sat",
"base_fee_sat",
"ppm_expiry_table"
],
"properties": {
"base_fee_sat": {
"type": "integer",
"format": "int64",
"description": "A fee applied to every transaction regardless of value.",
"minimum": 0
},
"min_fee_sat": {
"type": "integer",
"format": "int64",
"description": "Minimum fee to charge.",
"minimum": 0
},
"ppm_expiry_table": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PpmExpiryFeeEntry"
},
"description": "A table mapping how soon a VTXO will expire to a PPM (parts per million) fee rate.\nThe table should be sorted by each `expiry_blocks_threshold` value in ascending order."
}
}
},
"Movement": {
"type": "object",
"description": "Describes an attempted movement of offchain funds within the [bark::Wallet].",
"required": [
"id",
"status",
"subsystem",
"intended_balance_sat",
"effective_balance_sat",
"offchain_fee_sat",
"sent_to",
"received_on",
"input_vtxos",
"output_vtxos",
"exited_vtxos",
"time"
],
"properties": {
"effective_balance_sat": {
"type": "integer",
"format": "int64",
"description": "How much the wallet balance actually changed by. Positive numbers indicate an increase and\nnegative numbers indicate a decrease. This is often inclusive of applicable fees, and it\nshould be the most accurate number."
},
"exited_vtxos": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of IDs for VTXOs that were marked for unilateral exit as a result of this movement.\nThis could happen for many reasons, e.g. an unsuccessful lightning payment which can't be\nrevoked but is about to expire. VTXOs listed here will result in a reduction of spendable\nbalance due to the VTXOs being managed by the [bark::exit::Exit] system."
},
"id": {
"type": "integer",
"format": "int32",
"description": "The internal ID of the movement.",
"minimum": 0
},
"input_vtxos": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of [Vtxo](ark::Vtxo) IDs that were consumed by this movement and\nare either locked or unavailable."
},
"intended_balance_sat": {
"type": "integer",
"format": "int64",
"description": "How much the movement was expected to increase or decrease the balance by. This is always an\nestimate and often discounts any applicable fees."
},
"metadata": {
"type": [
"object",
"null"
],
"description": "Miscellaneous metadata for the movement. This is JSON containing arbitrary information as\ndefined by the subsystem that created the movement.",
"additionalProperties": {},
"propertyNames": {
"type": "string"
}
},
"offchain_fee_sat": {
"type": "integer",
"format": "int64",
"description": "How much the movement cost the user in offchain fees. If there are applicable onchain fees\nthey will not be included in this value but, depending on the subsystem, could be found in\nthe metadata.",
"minimum": 0
},
"output_vtxos": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of IDs for new VTXOs that were produced as a result of this movement. Often change\nVTXOs will be found here for outbound actions unless this was an inbound action."
},
"received_on": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MovementDestination"
},
"description": "Describes the means by which the wallet received funds in this movement. This could include\nBOLT11 invoices or other useful data."
},
"sent_to": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MovementDestination"
},
"description": "A list of external recipients that received funds from this movement."
},
"status": {
"$ref": "#/components/schemas/MovementStatus",
"description": "The status of the movement."
},
"subsystem": {
"$ref": "#/components/schemas/MovementSubsystem",
"description": "Contains information about the subsystem that created the movement as well as the purpose\nof the movement."
},
"time": {
"$ref": "#/components/schemas/MovementTimestamp",
"description": "Contains the times at which the movement was created, updated and completed."
}
}
},
"MovementDestination": {
"type": "object",
"description": "Describes a recipient of a movement. This could either be an external recipient in send actions\nor it could be the bark wallet itself.",
"required": [
"destination",
"amount_sat"
],
"properties": {
"amount_sat": {
"type": "integer",
"format": "int64",
"description": "How many sats the recipient received.",
"minimum": 0
},
"destination": {
"$ref": "#/components/schemas/PaymentMethod",
"description": "An address, invoice or any other identifier to distinguish the recipient."
}
}
},
"MovementStatus": {
"type": "string",
"enum": [
"pending",
"successful",
"failed",
"canceled"
]
},
"MovementSubsystem": {
"type": "object",
"description": "Contains information about the subsystem that created the movement as well as the purpose\nof the movement.",
"required": [
"name",
"kind"
],
"properties": {
"kind": {
"type": "string",
"description": "The action responsible for registering the movement."
},
"name": {
"type": "string",
"description": "The name of the subsystem that created and manages the movement."
}
}
},
"MovementTimestamp": {
"type": "object",
"description": "Contains the times at which the movement was created, updated and completed.",
"required": [
"created_at",
"updated_at"
],
"properties": {
"completed_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "The action responsible for registering the movement."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When the movement was first created."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "When the movement was last updated."
}
}
},
"NextRoundStart": {
"type": "object",
"required": [
"start_time"
],
"properties": {
"start_time": {
"type": "string",
"format": "date-time",
"description": "The next round start time in RFC 3339 format"
}
}
},
"NotFoundError": {
"type": "object",
"required": [
"resources",
"message"
],
"properties": {
"message": {
"type": "string"
},
"resources": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"OffboardAllFeeEstimateQuery": {
"type": "object",
"description": "Query parameters for offboard-all fee estimates.",
"required": [
"address"
],
"properties": {
"address": {
"type": "string",
"description": "The destination Bitcoin address"
}
}
},
"OffboardAllRequest": {
"type": "object",
"properties": {
"address": {
"type": [
"string",
"null"
],
"description": "Optional Bitcoin address to send to. If not provided, uses the onchain wallet's address"
}
}
},
"OffboardFees": {
"type": "object",
"description": "Fees for offboarding from the ark.",
"required": [
"base_fee_sat",
"fixed_additional_vb",
"ppm_expiry_table"
],
"properties": {
"base_fee_sat": {
"type": "integer",
"format": "int64",
"description": "A fee applied to every transaction regardless of value.",
"minimum": 0
},
"fixed_additional_vb": {
"type": "integer",
"format": "int64",
"description": "Fixed number of virtual bytes charged offboard on top of the output size\n\nThe fee for an offboard will be this value, plus the offboard output virtual size,\nmultiplied with the offboard fee rate, plus the `base_fee`, and plus the additional fee\ncalculated with the `ppm_expiry_table`.",
"minimum": 0
},
"ppm_expiry_table": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PpmExpiryFeeEntry"
},
"description": "A table mapping how soon a VTXO will expire to a PPM (parts per million) fee rate.\nThe table should be sorted by each `expiry_blocks_threshold` value in ascending order."
}
}
},
"OffboardResult": {
"type": "object",
"required": [
"offboard_txid"
],
"properties": {
"offboard_txid": {
"type": "string",
"description": "The transaction id of the offboard transaction"
}
}
},
"OffboardVtxosRequest": {
"type": "object",
"required": [
"vtxos"
],
"properties": {
"address": {
"type": [
"string",
"null"
],
"description": "Optional Bitcoin address to send to. If not provided, uses the onchain wallet's address"
},
"vtxos": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of VTXO IDs to offboard. The sum of the VTXOs being refreshed must be\n>= [P2TR_DUST](bitcoin_ext::P2TR_DUST) after the server-configured\n[OffboardFees](crate::cli::OffboardFees) are deducted."
}
}
},
"OnchainBalance": {
"type": "object",
"required": [
"total_sat",
"trusted_spendable_sat",
"immature_sat",
"trusted_pending_sat",
"untrusted_pending_sat",
"confirmed_sat"
],
"properties": {
"confirmed_sat": {
"type": "integer",
"format": "int64",
"description": "Confirmed and immediately spendable balance",
"minimum": 0
},
"immature_sat": {
"type": "integer",
"format": "int64",
"description": "All coinbase outputs not yet matured",
"minimum": 0
},
"total_sat": {
"type": "integer",
"format": "int64",
"description": "All of them combined.",
"minimum": 0
},
"trusted_pending_sat": {
"type": "integer",
"format": "int64",
"description": "Unconfirmed UTXOs generated by a wallet tx",
"minimum": 0
},
"trusted_spendable_sat": {
"type": "integer",
"format": "int64",
"description": "Get sum of trusted_pending and confirmed coins.\n\nThis is the balance you can spend right now that shouldn't get canceled via another party\ndouble spending it.",
"minimum": 0
},
"untrusted_pending_sat": {
"type": "integer",
"format": "int64",
"description": "Unconfirmed UTXOs received from an external wallet",
"minimum": 0
}
}
},
"OnchainDrainRequest": {
"type": "object",
"required": [
"destination"
],
"properties": {
"destination": {
"type": "string",
"description": "The destination Bitcoin address"
}
}
},
"OnchainFeeRatesResponse": {
"type": "object",
"description": "Mempool fee rates for on-chain transactions.",
"required": [
"fast_sat_per_vb",
"regular_sat_per_vb",
"slow_sat_per_vb"
],
"properties": {
"fast_sat_per_vb": {
"type": "integer",
"format": "int64",
"description": "Fee rate targeting ~1 block confirmation (sat/vB)",
"minimum": 0
},
"regular_sat_per_vb": {
"type": "integer",
"format": "int64",
"description": "Fee rate targeting ~3 block confirmation (sat/vB)",
"minimum": 0
},
"slow_sat_per_vb": {
"type": "integer",
"format": "int64",
"description": "Fee rate targeting ~6 block confirmation (sat/vB)",
"minimum": 0
}
}
},
"OnchainSendManyRequest": {
"type": "object",
"required": [
"destinations"
],
"properties": {
"destinations": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of destinations in format \"address:amount\""
},
"immediate": {
"type": [
"boolean",
"null"
],
"description": "Sends the transaction immediately instead of waiting"
}
}
},
"OnchainSendRequest": {
"type": "object",
"required": [
"destination",
"amount_sat"
],
"properties": {
"amount_sat": {
"type": "integer",
"format": "int64",
"description": "The amount to send (in satoshis)",
"minimum": 0
},
"destination": {
"type": "string",
"description": "The destination Bitcoin address"
}
}
},
"PaymentMethod": {
"type": "object",
"title": "PaymentMethod",
"description": "A payment method with a type discriminator and string value",
"required": [
"type",
"value"
],
"properties": {
"type": {
"type": "string",
"description": "The type of payment method",
"enum": [
"ark",
"bitcoin",
"output-script",
"invoice",
"offer",
"lightning-address",
"custom"
]
},
"value": {
"type": "string",
"description": "The payment method value (address, invoice, etc.)"
}
}
},
"PendingBoardInfo": {
"type": "object",
"description": "Describes a completed transition of funds from onchain to offchain.",
"required": [
"funding_tx",
"vtxos",
"amount_sat",
"movement_id"
],
"properties": {
"amount_sat": {
"type": "integer",
"format": "int64",
"description": "The amount of the board.",
"minimum": 0
},
"funding_tx": {
"$ref": "#/components/schemas/TransactionInfo",
"description": "The funding transaction.\nThis is the transaction that has to be confirmed\nonchain for the board to succeed."
},
"movement_id": {
"type": "integer",
"format": "int32",
"description": "The ID of the movement associated with this board.",
"minimum": 0
},
"vtxos": {
"type": "array",
"items": {
"type": "string"
},
"description": "The IDs of the VTXOs that were created\nin this board.\n\nCurrently, this is always a vector of length 1"
}
}
},
"PendingRoundInfo": {
"type": "object",
"required": [
"id",
"status",
"participation",
"unlock_hash",
"funding_txid"
],
"properties": {
"funding_tx_hex": {
"type": [
"string",
"null"
]
},
"funding_txid": {
"type": [
"string",
"null"
],
"description": "The round transaction id, if already assigned"
},
"id": {
"type": "integer",
"format": "int32",
"description": "Unique identifier for the round",
"minimum": 0
},
"participation": {
"$ref": "#/components/schemas/RoundParticipationInfo",
"description": "the round participation details"
},
"status": {
"$ref": "#/components/schemas/RoundStatus",
"description": "the current status of the round"
},
"unlock_hash": {
"type": [
"string",
"null"
]
}
}
},
"PpmExpiryFeeEntry": {
"type": "object",
"description": "Entry in a table to calculate the PPM (parts per million) fee rate of a transaction based on how\nnew a VTXO is.",
"required": [
"expiry_blocks_threshold",
"ppm"
],
"properties": {
"expiry_blocks_threshold": {
"type": "integer",
"format": "int32",
"description": "A threshold for the number of blocks until a VTXO expires for the `ppm` amount to apply.\nAs an example, if this value is set to 50 and a VTXO expires in 60 blocks, this\n[PpmExpiryFeeEntry] will be used to calculate the fee unless another entry exists with an\n`expiry_blocks_threshold` with a value between 51 and 60 (inclusive).",
"minimum": 0
},
"ppm": {
"type": "integer",
"format": "int64",
"description": "PPM (parts per million) fee rate to apply for this expiry period.",
"minimum": 0
}
}
},
"RefreshFees": {
"type": "object",
"description": "Fees for refresh operations.",
"required": [
"base_fee_sat",
"ppm_expiry_table"
],
"properties": {
"base_fee_sat": {
"type": "integer",
"format": "int64",
"description": "A fee applied to every transaction regardless of value.",
"minimum": 0
},
"ppm_expiry_table": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PpmExpiryFeeEntry"
},
"description": "A table mapping how soon a VTXO will expire to a PPM (parts per million) fee rate.\nThe table should be sorted by each `expiry_blocks_threshold` value in ascending order."
}
}
},
"RefreshRequest": {
"type": "object",
"required": [
"vtxos"
],
"properties": {
"vtxos": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of VTXO IDs to refresh. The sum of the VTXOs being refreshed must be\n>= [P2TR_DUST](bitcoin_ext::P2TR_DUST). Keep in mind that fees set out in\n[RefreshFees](crate::cli::RefreshFees) will be deducted from the newly created VTXO, this\nvalue must also be >= [P2TR_DUST](bitcoin_ext::P2TR_DUST)."
}
}
},
"RoundParticipationInfo": {
"type": "object",
"required": [
"inputs",
"outputs"
],
"properties": {
"inputs": {
"type": "array",
"items": {
"type": "string"
}
},
"outputs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/VtxoRequestInfo"
}
}
}
},
"RoundStatus": {
"oneOf": [
{
"type": "object",
"description": "Failed to sync round",
"required": [
"error",
"status"
],
"properties": {
"error": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"sync-error"
]
}
}
},
{
"type": "object",
"description": "The round was successful and is fully confirmed",
"required": [
"funding_txid",
"status"
],
"properties": {
"funding_txid": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"confirmed"
]
}
}
},
{
"type": "object",
"description": "Round successful but not fully confirmed",
"required": [
"funding_txid",
"status"
],
"properties": {
"funding_txid": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"unconfirmed"
]
}
}
},
{
"type": "object",
"description": "We have unsigned funding transactions that might confirm",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"pending"
]
}
}
},
{
"type": "object",
"description": "The round failed",
"required": [
"error",
"status"
],
"properties": {
"error": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"failed"
]
}
}
},
{
"type": "object",
"description": "The round canceled",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"canceled"
]
}
}
}
]
},
"Send": {
"type": "object",
"required": [
"txid"
],
"properties": {
"txid": {
"type": "string"
}
}
},
"SendOnchainFeeEstimateQuery": {
"type": "object",
"description": "Query parameters for send-onchain fee estimates.",
"required": [
"amount_sat",
"address"
],
"properties": {
"address": {
"type": "string",
"description": "The destination Bitcoin address"
},
"amount_sat": {
"type": "integer",
"format": "int64",
"description": "The amount in satoshis to send",
"minimum": 0
}
}
},
"SendOnchainRequest": {
"type": "object",
"required": [
"destination",
"amount_sat"
],
"properties": {
"amount_sat": {
"type": "integer",
"format": "int64",
"description": "The amount (in satoshis) to be received by `destination` onchain. Must be\n>= [P2TR_DUST](bitcoin_ext::P2TR_DUST). Server-configured fees laid out in\n[OffboardFees](crate::cli::OffboardFees) will be added on top of this amount.",
"minimum": 0
},
"destination": {
"type": "string",
"description": "The destination Bitcoin address"
}
}
},
"SendRequest": {
"type": "object",
"required": [
"destination"
],
"properties": {
"amount_sat": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The amount to send (in satoshis). Optional for bolt11 invoices. Depending on the\n`destination`, the wallet must contain this amount plus any fees configured by the server in\n[FeeSchedule](crate::cli::FeeSchedule).",
"minimum": 0
},
"comment": {
"type": [
"string",
"null"
],
"description": "An optional comment, only supported when paying to lightning addresses"
},
"destination": {
"type": "string",
"description": "The destination can be an Ark address, a BOLT11-invoice, LNURL or a lightning address"
}
}
},
"SendResponse": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"description": "Success message"
}
}
},
"TipResponse": {
"type": "object",
"required": [
"tip_height"
],
"properties": {
"tip_height": {
"type": "integer",
"format": "int32",
"minimum": 0
}
}
},
"TransactionInfo": {
"type": "object",
"description": "An information struct used to pair the ID of a transaction with the full transaction for ease\nof use and readability for the user",
"required": [
"txid",
"tx"
],
"properties": {
"tx": {
"type": "string"
},
"txid": {
"type": "string"
}
}
},
"UtxoInfo": {
"type": "object",
"description": "Struct representing information about an Unspent Transaction Output (UTXO).\n\nThis structure provides details about a UTXO, which includes the outpoint (transaction ID and\nindex), the associated amount in satoshis, and the block height at which the transaction was\nconfirmed (if available).\n\n# Serde Behavior\n\n* The `amount` field is serialized and deserialized with a custom function from the `bitcoin`\n crate that ensures the value is interpreted as satoshis with the name `amount_sat`.",
"required": [
"outpoint",
"amount_sat"
],
"properties": {
"amount_sat": {
"type": "integer",
"format": "int64",
"description": "The value of the UTXO in satoshis.",
"minimum": 0
},
"confirmation_height": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "An optional field that specifies the block height at which the transaction was confirmed. If\nthe transaction is unconfirmed, this value will be `None`.",
"minimum": 0
},
"outpoint": {
"type": "string",
"description": "Contains the reference to the specific transaction output via transaction ID and index."
}
}
},
"VtxoInfo": {
"type": "object",
"description": "Information about a single VTXO (Virtual Transaction Output).\n\nA VTXO is a chain of off-chain, pre-signed transactions rooted in an\non-chain output. It represents spendable bitcoin on Ark.",
"required": [
"id",
"amount_sat",
"policy_type",
"user_pubkey",
"server_pubkey",
"expiry_height",
"exit_delta",
"chain_anchor"
],
"properties": {
"amount_sat": {
"type": "integer",
"format": "int64",
"description": "The value of this VTXO in sats.",
"minimum": 0
},
"chain_anchor": {
"type": "string",
"description": "The on-chain outpoint that roots this VTXO, formatted as\n`txid:vout`. Typically an output of a round transaction or a\nboard transaction."
},
"exit_delta": {
"$ref": "#/components/schemas/u16",
"description": "The relative timelock, in blocks, that must elapse before the\nfinal on-chain claim in an emergency exit."
},
"exit_depth": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "The number of off-chain transactions in this VTXO. Each must\nbe broadcast and confirmed on-chain in sequence during an\nemergency exit.",
"minimum": 0
},
"expiry_height": {
"$ref": "#/components/schemas/u32",
"description": "The block height at which this VTXO expires. After expiry, the\nserver can reclaim the sats. Refresh before expiry to receive\nnew VTXOs, or exit to move them on-chain."
},
"id": {
"type": "string",
"description": "Unique identifier for this VTXO, formatted as `txid:vout`."
},
"policy_type": {
"type": "string",
"description": "The spending policy that governs this VTXO."
},
"server_pubkey": {
"type": "string",
"description": "The Ark server's public key used to co-sign transactions\ninvolving this VTXO."
},
"user_pubkey": {
"type": "string",
"description": "The owner's public key. Only the holder of the corresponding\nprivate key can spend this VTXO."
}
}
},
"VtxoRequestInfo": {
"type": "object",
"required": [
"amount_sat",
"policy_type",
"user_pubkey"
],
"properties": {
"amount_sat": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"policy_type": {
"type": "string"
},
"user_pubkey": {
"type": "string"
}
}
},
"VtxoStateInfo": {
"oneOf": [
{
"type": "object",
"description": "The VTXO can be spent immediately.",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"spendable"
]
}
}
},
{
"type": "object",
"description": "The VTXO has already been spent.",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"spent"
]
}
}
},
{
"type": "object",
"description": "The VTXO is locked by an in-progress movement (e.g. a pending\nround or Lightning payment).",
"required": [
"type"
],
"properties": {
"movement_id": {
"type": "integer",
"format": "int32",
"description": "The movement that locked this VTXO, if any.",
"minimum": 0
},
"type": {
"type": "string",
"enum": [
"locked"
]
}
}
}
],
"description": "The current state of a VTXO in the wallet."
},
"VtxosQuery": {
"type": "object",
"properties": {
"all": {
"type": [
"boolean",
"null"
],
"description": "Return all VTXOs regardless of their state (including spent ones)"
}
}
},
"WalletDeleteRequest": {
"type": "object",
"required": [
"dangerous",
"fingerprint"
],
"properties": {
"dangerous": {
"type": "boolean"
},
"fingerprint": {
"type": "string"
}
}
},
"WalletDeleteResponse": {
"type": "object",
"required": [
"deleted",
"message"
],
"properties": {
"deleted": {
"type": "boolean"
},
"message": {
"type": "string"
}
}
},
"WalletExistsResponse": {
"type": "object",
"properties": {
"fingerprint": {
"type": [
"string",
"null"
]
}
}
},
"WalletVtxoInfo": {
"allOf": [
{
"$ref": "#/components/schemas/VtxoInfo",
"description": "The VTXO details."
},
{
"type": "object",
"required": [
"state"
],
"properties": {
"state": {
"$ref": "#/components/schemas/VtxoStateInfo",
"description": "The current state of this VTXO in the wallet."
}
}
}
],
"description": "A VTXO together with its current wallet state."
},
"u16": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"u32": {
"type": "integer",
"format": "int32",
"minimum": 0
}
},
"securitySchemes": {
"bearer": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "AuthToken",
"description": "Base64url-encoded auth token"
}
}
},
"security": [
{
"bearer": []
}
],
"tags": [
{
"name": "boards",
"description": "Move on-chain bitcoin onto the Ark protocol."
},
{
"name": "exits",
"description": "Move bitcoin back on-chain without server cooperation."
},
{
"name": "fees",
"description": "Estimate fees for wallet operations before executing them."
},
{
"name": "lightning",
"description": "Create Lightning invoices and track receives."
},
{
"name": "onchain",
"description": "Manage barkd's on-chain bitcoin wallet."
},
{
"name": "wallet",
"description": "Manage Ark balances and VTXOs, send payments via Ark, LN, and on-chain."
},
{
"name": "bitcoin",
"description": "Query bitcoin network data."
}
]
}