Skip to Content
Bsa Partner IntegrationAPI States

API States

Response payload

Payload to return after request to GET /v2/bsa/tranches

{
  "page_info": {
    "limit": 1,
    "offset": 1,
    "order": "ORDER_UNSPECIFIED",
    "total": 1
  },
  "current_btc_block": "string",
  "current_eth_block": "string",
  "tranches": [
    {
      "outpoint": "string", // UTXO to the vault address in format txid:vout
      "request_id": "string", // request id identifying the add operation this tranche was created with
      "created_at": "2026-07-07T09:03:13.208Z", // ISO 8601 timestamp
      "updated_at": "2026-07-07T09:03:13.208Z", // ISO 8601 timestamp
      "amount_sat": "string", // the amount in satoshi
      "ui_state": "string", // a summary state for UI/UX usage
      "btc_state": "string", // state according to the Bitcoin blockchain
      "btc_state_timelock_expiry_blocknum": null | "string", // Bitcoin block number which will cause a btc_state change by timelock expiration. Null if no expiration applies to current state
      "defi_state": "string", // finalized state according to the SAR on the destination chain
      "defi_pending_state": "string", // yet to finalize state according to the SAR on the destination chain
      "vault_address": "string",
      "defi_address": "string",
      "unlock_address": "string",
      "hint_ao_intervention": true | false,
      "defi_txs": {
        "record": null | "string",
        "mint": null | "string",
        "rebalance": null | "string",
        "unlock": null | "string"
      },
      "btc_txs": { // txid according to the explorers byte ordering
        "deposit": null | "string",
        "unlock": null | "string", // the unilateral unlock
        "unlock_coop": null | "string",
        "unlock_challenge": null | "string",
        "rebalance": null | "string",
        "ao_resolution": null | "string", // either from uca or rca
        "claim": null | "string" // any transaction pulling funds from timelock addresses (uta, uca, rca)
      }
    },
    ...
  ]
}

Extended tranche model

In case the GET request brings an extended=true query param, then the tranche model in the tranches field will also carry the following fields

{
  "internal_state": "string", // a fine-grained state reporting the most accurate tranche lifecycle state used by backend services
  "notary_session": { // notary session ids associated with the tranche lifecycle
    "deposit": null | { // deposit "DepositBSA" selector
      "id": "string", // session id
      "payload": "string", // hex encoded payload
      "proof": "string" // hex abi-encoded proof
    },
    "unlock": null | {
      "id": "string" // session id
    },
    "reject": null | {
      "id": "string" // session id
    }
  }
}

App Status

Note Sub bullet points with the 💡 icon are possible user actions.

  • ui_state
    • setup:
      1. Lombard PSBT signing
      2. Registration on SAR
    • awaiting_btc_deposit: Anchorage must make deposit to the vault address generated in Lock. defi_state.recorded && btc_state.pending_deposit
    • activating: Anchorage has made BTC deposit, Lombard is waiting for block confirmations before minting on Destination Chain (defi_state.recorded && btc_state.awaiting_lock) || (btc_state.locked && defi_pending_state.minted)
      • 💡 Reject (on SAR)
    • rejected: defi_state.user_rejected
      • 💡 Unlock (on BTC)
    • active: defi_state.minted
      • 💡 Unlock (Coop) if BTC.b balance for the defi_address ≥ tranche.amount
    • rebalancing: defi_pending_state.rebalanced || defi_state.rebalanced || btc_state.rebalancing || btc_state.rebalance_expired || btc_state.unlock_challenge || btc_state.unlock_challenge_expired
      • 💡 Request AO Intervention (if hint_ao_intervention)
    • rebalanced: btc_state.rebalance_successful || btc_state.unlock_challenge_succesful
    • unlocking: btc_state.unlocking(T) || defi_pending_state.unlocked
      • 💡 if defi_state.unlocked && !btc_state.unlocking(T) after T in a cooperative unlock, can start “Unlock on BTC” if TO did nothing
    • unlock_claim_available: btc_state.unlock_claim_available
      • 💡 Finalize Unlock
    • unlocked: btc_state.unlock_challenge_ao_claimed || btc_state.rebalance_ao_claimed || btc_state.unlocked

hint_ao_intervention = btc_state.rebalancing || btc_state.unlock_challenge || btc_state.unlock_challenge_expired || btc_state.rebalance_expired

Destination Network Statuses

  • defi_state // on Ethereum this is 64 blocks ~12 min
    • recorded
    • minted
    • user_rejected
    • unlocked_unilateral
    • unlocked_coop
    • rebalanced
  • defi_pending_state is the same as defi_state but based on 1 block confirmation only. The value is the same as defi_state. The state that is going to be in defi_state upon finalized state of ethereum.

Bitcoin Network Statuses

Note If T is specified we should expose this in the API e.g. as an optional btc_state_timelock_expiry_blocknum parameter based on the current state i.e. set for unlocking and rebalancing, null when in other states.

  • btc_state // 6 confirmations. Lower item takes priority.
    • pending_deposit: Deposit requested, vault address has not yet received a deposit
    • awaiting_lock: deposit transaction detected by not yet finalized to 6 confirmations, but we have registered (tranche) request. Distinction: even when deposit made to user vault, status remains until 6 confirmations reached.
    • locked: Funds have been finalized in Vault Address state.
      • unlocked_coop: UTXO has already been sent back to depositor by the TO
    • unlocking(T): User has transacted funds from VA to UTA address.
      • unlock_claim_available: User can pull funds from their UTA address after T (relative time lock expired compared to the current Bitcoin block in the Backend API, not 6 block delay) N.B: TO can still pull funds if funds are available
        • unlocked: User has pulled funds from their UTA address
      • unlock_challenge(T): TO has transacted funds from UTA to UCA
        • unlock_challenge_ao_resolve: AO transacted funds from UCA to depositor
        • unlock_challenge_expired: TO can pull funds from UCA after T
          • unlock_challenge_successful: TO did pull funds from UCA
    • rebalancing(T): TO has transacted funds from VA to RCA address.
      • rebalance_ao_resolved: AO transacted funds from RCA to depositor
      • rebalance_expired: TO can pull funds from RCA after T
        • rebalance_successful: TO did pull funds from RCA

← Back to BSA Integration Overview

Last updated on
BSA Integration GuideBSA Arbitration Oracle Handbook