Import a VTXO
Imports the hex-encoded serialized VTXOs in the request body into the wallet; it does not read them from the server mailbox. Validates that each VTXO is anchored on-chain and owned by this wallet. Useful for restoring VTXOs after database loss, or for re-importing ones obtained elsewhere. Ownership is resolved by scanning the seed-derived key space, bounded by gap_limit or the wallet’s configured gap limit; a key the scan does not reach is a 400. Only VTXOs the server reports as spendable or spent are stored, in that state, so one that has already been spent is recorded as spent rather than rejected. A VTXO still in flight (unclaimed, unregistered, or awaiting a preimage) is rejected with a 422, because it becomes importable once that flow finishes. Pass skip_status_check to store them as spendable without asking the server. Expiry is not checked. The VTXOs are imported together, in one key scan and one transaction, so a rejected VTXO leaves none of them stored; pass allow_partial to keep the VTXOs that did import, and the response then lists only those. Already-imported VTXOs are skipped, so the operation is idempotent and a failed request can be retried.
Authorizations
Base64url-encoded auth token
Body
Hex-encoded VTXOs to import
Keep the VTXOs that import successfully even when another one in the request fails. The response lists the VTXOs that were kept.
Without it, a single failure discards the whole request.
How many consecutive unused key indices to scan for each VTXO's user pubkey. Overrides the wallet's configured gap limit.
0 <= x <= 100000Import as spendable without asking the server for each VTXO's state.
Use it when you already know it's spendable or when the server can't be reached, as it can leave the wallet in an inconsistent state.
Response
VTXO imported successfully
The value of this VTXO in sats.
x >= 0The on-chain outpoint that roots this VTXO, formatted as
txid:vout. Typically an output of a round transaction or a
board transaction.
The relative timelock, in blocks, that must elapse before the final on-chain claim in an emergency exit.
x >= 0The block height at which this VTXO expires. After expiry, the server can reclaim the sats. Refresh before expiry to receive new VTXOs, or exit to move them on-chain.
x >= 0Unique identifier for this VTXO, formatted as txid:vout.
The spending policy that governs this VTXO.
The Ark server's public key used to co-sign transactions involving this VTXO.
The owner's public key. Only the holder of the corresponding private key can spend this VTXO.
The current state of this VTXO in the wallet.
- Option 1
- Option 2
- Option 3
- Option 4
The number of off-chain transactions in this VTXO. Each must be broadcast and confirmed on-chain in sequence during an emergency exit.
x >= 0