> ## Documentation Index > Fetch the complete documentation index at: https://second.tech/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml https://gitlab.com/ark-bitcoin/bark/-/raw/master/bark-rest/openapi.json post /api/v1/wallet/import-vtxo 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. barkd is a long-running daemon best suited for always-on or high-connectivity environments like nodes, servers, desktops, and point-of-sale terminals. All endpoints return JSON. Amounts are denominated in satoshis. contact: name: Second Team email: hello@second.tech license: name: MIT identifier: MIT version: 0.7.1 servers: [] 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: history description: Inspect and annotate wallet movement history. - name: lightning description: Create Lightning invoices and track receives. - name: message description: Sign arbitrary messages with the wallet's keys and verify signed messages. - 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. - name: notifications description: Receive real-time notifications from barkd. paths: /api/v1/wallet/import-vtxo: post: tags: - wallet summary: Import a VTXO description: >- 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. 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, a VTXO that does not match the chain, or a VTXO whose user pubkey is not derivable from this seed within the gap limit content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '422': description: >- The VTXO is neither spendable nor spent, so it cannot be imported yet content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalServerError' components: schemas: ImportVtxoRequest: type: object required: - vtxos properties: allow_partial: type: boolean description: |- 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. gap_limit: type: - integer - 'null' format: int32 description: |- How many consecutive unused key indices to scan for each VTXO's user pubkey. Overrides the wallet's configured gap limit. maximum: 100000 minimum: 0 skip_status_check: type: boolean description: >- Import 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. vtxos: type: array items: type: string description: Hex-encoded VTXOs to import 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. BadRequestError: type: object required: - message properties: message: type: string UnprocessableEntityError: type: object required: - message properties: message: type: string InternalServerError: type: object required: - message properties: message: type: string VtxoInfo: type: object description: |- Information about a single VTXO (Virtual Transaction Output). A VTXO is a chain of off-chain, pre-signed transactions rooted in an on-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 `txid:vout`. Typically an output of a round transaction or a board transaction. exit_delta: $ref: '#/components/schemas/u16' description: |- The relative timelock, in blocks, that must elapse before the final 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 be broadcast and confirmed on-chain in sequence during an emergency exit. minimum: 0 expiry_height: $ref: '#/components/schemas/u32' description: |- The 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. 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 involving this VTXO. user_pubkey: type: string description: |- The owner's public key. Only the holder of the corresponding private key can spend this VTXO. 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 has been moved on-chain via a unilateral exit and is no longer usable in the protocol. required: - type properties: type: type: string enum: - exited - type: object description: |- The VTXO is locked by an in-progress movement (e.g. a pending round or Lightning payment). required: - type properties: action_id: type: string description: The action that locked this VTXO, if any. 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. 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 ````