Wallet endpoints

Wallet endpoints manage your Ark balance and handle sending payments via Ark, Lightning, and on-chain.

Check server connection

GET /api/v1/wallet/connected

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.

Response

{
  "connected": true
}

Create a wallet

POST /api/v1/wallet/create

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.

Request body

{
  "ark_server": "https://ark.second.tech",
  "network": "mainnet",
  "chain_source": {
    "esplora": {
      "url": "https://mempool.space/api"
    }
  },
  "mnemonic": "word1 word2 ... word24",
  "birthday_height": 800000
}

Parameters:

ark_server (string, required) - The Ark server URL
network (string, required) - Network: mainnet, signet, mutinynet, or regtest
chain_source (object, required) - Chain source configuration (see below)
mnemonic (string, optional) - BIP39 seed phrase. If omitted, a new one is generated
birthday_height (integer, optional) - Block height to start syncing from

Chain source options: Esplora:

{
  "esplora": {
    "url": "https://mempool.space/api"
  }
}

Bitcoind:

{
  "bitcoind": {
    "bitcoind": "http://localhost:8332",
    "bitcoind_auth": {
      "user-pass": {
        "user": "bitcoin",
        "pass": "password"
      }
    }
  }
}

Or with cookie authentication:

{
  "bitcoind": {
    "bitcoind": "http://localhost:8332",
    "bitcoind_auth": {
      "cookie": {
        "cookie": "/path/to/.cookie"
      }
    }
  }
}

Response

{
  "fingerprint": "a1b2c3d4"
}

Get Ark server info

GET /api/v1/wallet/ark-info

Returns the Ark server’s configuration parameters, including network, public key, round interval, VTXO expiry and exit deltas, fee settings, and Lightning support details.

Response

{
  "network": "mainnet",
  "pubkey": "02...",
  "round_interval": 600,
  "vtxo_expiry_delta": 2016,
  "vtxo_exit_delta": 512,
  "board_fees": {
    "min_fee_sat": 1000,
    "base_fee_sat": 0,
    "ppm": 1000
  },
  "lightning": {
    "enabled": true,
    "cltv_expiry_delta": 144
  }
}

Errors

404 - Wallet not connected to an Ark server

Get next round time

GET /api/v1/wallet/next-round

Queries the Ark server for the next scheduled round start time and returns it in RFC 3339 format.

Response

{
  "start_time": "2026-03-03T15:30:00Z"
}

Errors

404 - Wallet not connected to an Ark server

Generate Ark address

POST /api/v1/wallet/addresses/next

Generates a new Ark receiving address. Each call returns the next unused address from the wallet’s HD keychain.

Response

{
  "address": "ark1..."
}

Example

curl -X POST http://localhost:3000/api/v1/wallet/addresses/next

Get Ark address by index

GET /api/v1/wallet/addresses/index/{index}

Returns a previously generated Ark address by its derivation index. Only addresses that have already been generated are available.

Path parameters

index (integer, required) - Address derivation index

Response

{
  "address": "ark1..."
}

Example

curl http://localhost:3000/api/v1/wallet/addresses/index/0

Get wallet balance

GET /api/v1/wallet/balance

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.

Response

{
  "spendable_sat": 100000,
  "pending_round_sat": 0,
  "pending_lightning_outbound_sat": 0,
  "pending_lightning_inbound_sat": 0,
  "pending_board_sat": 0,
  "pending_exit_sat": 0
}

Example

curl http://localhost:3000/api/v1/wallet/balance

List VTXOs

GET /api/v1/wallet/vtxos

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.

Query parameters

all (boolean, optional) - Return all VTXOs regardless of state. Default: false

Response

[
  {
    "vtxo": {
      "id": "0123456789abcdef...",
      "amount_sat": 50000,
      "expiry_height": 850000,
      "spec": "..."
    },
    "state": {
      "spendable": {}
    }
  }
]

Example

curl http://localhost:3000/api/v1/wallet/vtxos

curl http://localhost:3000/api/v1/wallet/vtxos?all=true

Get wallet history

GET /api/v1/wallet/history

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.

Response

[
  {
    "movement_type": "arkoor_send",
    "timestamp": "2026-03-03T10:00:00Z",
    "amount_sat": -10000,
    "fee_sat": 100,
    "status": "completed",
    "inputs": ["vtxo_id_1"],
    "outputs": ["vtxo_id_2"]
  }
]

List round participations

GET /api/v1/wallet/rounds

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 (two confirmations on mainnet, one 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.

Response

[
  {
    "round_id": "abc123...",
    "status": "waiting_for_round",
    "created_at": "2026-03-03T10:00:00Z"
  }
]

Send a payment

POST /api/v1/wallet/send

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.

Request body

{
  "destination": "ark1...",
  "amount_sat": 10000,
  "comment": "Coffee payment"
}

Parameters:

destination (string, required) - Ark address, BOLT11 invoice, BOLT12 offer, or Lightning address
amount_sat (integer, optional) - Amount in satoshis. Required for Ark addresses and Lightning addresses
comment (string, optional) - Comment (only supported for Lightning addresses)

Response

{
  "message": "Payment sent successfully"
}

Examples

# Send to Ark address
curl -X POST http://localhost:3000/api/v1/wallet/send \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "ark1qpzry9x8gf2tvdw0s3jn54khce6mua7l...",
    "amount_sat": 10000
  }'

# Pay BOLT11 invoice
curl -X POST http://localhost:3000/api/v1/wallet/send \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "lnbc100n1..."
  }'

# Pay Lightning address
curl -X POST http://localhost:3000/api/v1/wallet/send \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "[email protected]",
    "amount_sat": 5000,
    "comment": "Thanks for the coffee!"
  }'

Errors

400 - Invalid destination format or missing required amount

Refresh specific VTXOs

POST /api/v1/wallet/refresh/vtxos

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.

Request body

{
  "vtxos": [
    "0123456789abcdef...",
    "fedcba9876543210..."
  ]
}

Parameters:

vtxos (array of strings, required) - VTXO IDs to refresh

Response

{
  "round_id": "abc123...",
  "status": "waiting_for_round",
  "created_at": "2026-03-03T10:00:00Z"
}

Errors

400 - No VTXO IDs provided or invalid VTXO ID
404 - One of the VTXOs wasn’t found

Refresh all VTXOs

POST /api/v1/wallet/refresh/all

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.

Response

{
  "round_id": "abc123...",
  "status": "waiting_for_round",
  "created_at": "2026-03-03T10:00:00Z"
}

Example

curl -X POST http://localhost:3000/api/v1/wallet/refresh/all

Refresh received VTXOs

POST /api/v1/wallet/refresh/counterparty

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.

Response

{
  "round_id": "abc123...",
  "status": "waiting_for_round",
  "created_at": "2026-03-03T10:00:00Z"
}

Errors

404 - No VTXOs to refresh

Offboard specific VTXOs

POST /api/v1/wallet/offboard/vtxos

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.

Request body

{
  "vtxos": [
    "0123456789abcdef...",
    "fedcba9876543210..."
  ],
  "address": "bc1q..."
}

Parameters:

vtxos (array of strings, required) - VTXO IDs to offboard
address (string, optional) - Destination bitcoin address. If omitted, a new address is generated

Response

{
  "offboard_txid": "abc123..."
}

Errors

400 - No VTXO IDs provided, invalid VTXO ID, or invalid address
404 - One of the VTXOs wasn’t found

Offboard all VTXOs

POST /api/v1/wallet/offboard/all

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.

Request body

{
  "address": "bc1q..."
}

Parameters:

address (string, optional) - Destination bitcoin address. If omitted, a new address is generated

Response

{
  "offboard_txid": "abc123..."
}

Send on-chain from Ark balance

POST /api/v1/wallet/send-onchain

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.

Request body

{
  "destination": "bc1q...",
  "amount_sat": 50000
}

Parameters:

destination (string, required) - Bitcoin address
amount_sat (integer, required) - Amount in satoshis

Response

{
  "offboard_txid": "abc123..."
}

Example

curl -X POST http://localhost:3000/api/v1/wallet/send-onchain \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "amount_sat": 50000
  }'

Sync wallet

POST /api/v1/wallet/sync

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.

Response

Returns 200 on success with no body.

Example

curl -X POST http://localhost:3000/api/v1/wallet/sync

Import a VTXO

POST /api/v1/wallet/import-vtxo

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.

Request body

{
  "vtxos": [
    "0a1b2c3d...",
    "4e5f6a7b..."
  ]
}

Parameters:

vtxos (array of strings, required) - Hex-encoded VTXOs to import

Response

[
  {
    "vtxo": {
      "id": "0123456789abcdef...",
      "amount_sat": 50000,
      "expiry_height": 850000
    },
    "state": {
      "spendable": {}
    }
  }
]

Errors

400 - Invalid VTXO hex or VTXO not owned by wallet

Wallet API

Protocol Primitives

REST API

​Check server connection

​Response

​Create a wallet

​Request body

​Response

​Get Ark server info

​Response

​Errors

​Get next round time

​Response

​Errors

​Generate Ark address

​Response

​Example

​Get Ark address by index

​Path parameters

​Response

​Example

​Get wallet balance

​Response

​Example

​List VTXOs

​Query parameters

​Response

​Example

​Get wallet history

​Response

​List round participations

​Response

​Send a payment

​Request body

​Response

​Examples

​Errors

​Refresh specific VTXOs

​Request body

​Response

​Errors

​Refresh all VTXOs

​Response

​Example

​Refresh received VTXOs

​Response

​Errors

​Offboard specific VTXOs

​Request body

​Response

​Errors

​Offboard all VTXOs

​Request body

​Response

​Send on-chain from Ark balance

​Request body

​Response

​Example

​Sync wallet

​Response

​Example

​Import a VTXO

​Request body

​Response

​Errors

Build docs developers (and LLMs) love

Check server connection

Response

Create a wallet

Request body

Response

Get Ark server info

Response

Errors

Get next round time

Response

Errors

Generate Ark address

Response

Example

Get Ark address by index

Path parameters

Response

Example

Get wallet balance

Response

Example

List VTXOs

Query parameters

Response

Example

Get wallet history

Response

List round participations

Response

Send a payment

Request body

Response

Examples

Errors

Refresh specific VTXOs

Request body

Response

Errors

Refresh all VTXOs

Response

Example

Refresh received VTXOs

Response

Errors

Offboard specific VTXOs

Request body

Response

Errors

Offboard all VTXOs

Request body

Response

Send on-chain from Ark balance

Request body

Response

Example

Sync wallet

Response

Example

Import a VTXO

Request body

Response

Errors