Types

Shared types for API requests, responses, and swap state.

Re-exports the OpenAPI-generated request/response types and enums, and adds SwapInStatus and SwapOutStatus - discriminated unions keyed by status that model each swap direction's lifecycle, carrying only the fields available in each state.

Enumerations

Chain

Enumeration Members

Enumeration Member	Value
`Bitcoin`	`"bitcoin"`
`Liquid`	`"liquid"`

ErrorCode

Machine-readable code carried beside message in every error response, so a client never infers semantics from the HTTP status.

Enumeration Members

Enumeration Member	Value
`BadRequest`	`"BadRequest"`
`Forbidden`	`"Forbidden"`
`InsufficientLiquidity`	`"InsufficientLiquidity"`
`Internal`	`"Internal"`
`NotImplemented`	`"NotImplemented"`
`PayloadTooLarge`	`"PayloadTooLarge"`
`PolicyError`	`"PolicyError"`
`QuoteExpired`	`"QuoteExpired"`
`SwapAlreadyExists`	`"SwapAlreadyExists"`
`SwapNotFound`	`"SwapNotFound"`
`TooManyConnections`	`"TooManyConnections"`
`TransitionRejected`	`"TransitionRejected"`
`Unavailable`	`"Unavailable"`

SwapNetwork

On-chain network for swap operations.

Enumeration Members

Enumeration Member	Value
`Mainnet`	`"mainnet"`
`Regtest`	`"regtest"`
`Signet`	`"signet"`
`Testnet`	`"testnet"`

SwapType

Swap kind. Directions are relative to Lightning: SwapIn is on-chain to Lightning, SwapOut is Lightning to on-chain, SwapChain is on-chain to on-chain across two different chains.

Enumeration Members

Enumeration Member	Value
`SwapChain`	`"SwapChain"`
`SwapIn`	`"SwapIn"`
`SwapOut`	`"SwapOut"`

Interfaces

ApiError

Error body returned by the server on a non-2xx response. Branch on code rather than message or the HTTP status; the fields are absent only when the body could not be parsed.

Properties

Property	Type
`code?`	`ErrorCode`
`message?`	`string`

AssetPolicyResponse

Properties

Property	Type
`asset_id`	`string`
`max_amount`	`string`
`min_amount`	`string`

CancelRequest

Properties

Property	Type
`cancel_message`	`string`

ChainPolicyResponse

Properties

Property	Type	Description
`asset`	`Partial`<`Record`<`string`, `AssetPolicyResponse`>>	-
`block_time`	`number`	Min 0
`confs`	`number`	Min 0
`dest_csv`	`number`	CSV timelock on a swap-out opening tx, in this chain's blocks. Min 0
`min_base_fee_multiplier`	`number`	Dust-guard floor: minimum receive amount as a multiple of this chain's base fee. Min 0
`service_ppm`	`number`	Min 0
`source_csv`	`number`	CSV timelock on a swap-in opening tx, in this chain's blocks. Min 0
`timeouts`	`TimeoutResponse`	Deadlines this chain enforces as a SwapIn source, in seconds. A swap left in the matching status past its deadline is canceled. SwapOut has no deadline here: once its opening tx confirms, the bound is the `dest_csv` timelock in blocks.

CreateSwapRequest

Body of createSwap. As the service documents it, amounts as decimal strings, except that webhook.statuses are typed to the statuses a swap can reach, so a misspelled one fails to compile.

Extends

Omit<GeneratedCreateSwapRequest, "webhook">

Properties

Property	Type	Description	Inherited from
`claim_invoice?`	`string` \| `null`	swap-in only.	`Omit.claim_invoice`
`dest_asset_id?`	`string` \| `null`	-	`Omit.dest_asset_id`
`dest_blinding_pubkey?`	`string` \| `null`	swap-out and swap-chain, Liquid only.	`Omit.dest_blinding_pubkey`
`dest_chain?`	`Chain` \| `null`	-	`Omit.dest_chain`
`dest_claim_pubkey?`	`string` \| `null`	swap-out and swap-chain.	`Omit.dest_claim_pubkey`
`payment_hash?`	`string` \| `null`	swap-out and swap-chain: preimage hash for the destination HTLC.	`Omit.payment_hash`
`protocol_version`	`string`	-	`Omit.protocol_version`
`quote_id?`	`string` \| `null`	Optional `GET /v1/info` quote locking the base fee.	`Omit.quote_id`
`receive_amount`	`string`	-	`Omit.receive_amount`
`send_amount`	`string`	-	`Omit.send_amount`
`source_asset_id?`	`string` \| `null`	-	`Omit.source_asset_id`
`source_blinding_pubkey?`	`string` \| `null`	swap-in and swap-chain, Liquid only.	`Omit.source_blinding_pubkey`
`source_chain?`	`Chain` \| `null`	-	`Omit.source_chain`
`source_refund_pubkey?`	`string` \| `null`	swap-in and swap-chain.	`Omit.source_refund_pubkey`
`swap_id`	`string`	-	`Omit.swap_id`
`user_claim_address?`	`string` \| `null`	swap-out and swap-chain.	`Omit.user_claim_address`
`user_id`	`string`	-	`Omit.user_id`
`user_refund_address?`	`string` \| `null`	swap-in and swap-chain.	`Omit.user_refund_address`
`webhook?`	`SwapWebhook`<`SwapStatus`> \| `null`	Status webhook to register with the swap.	-

FeeEstimate

Properties

Property	Type
`dest`	`string`
`source`	`string`

InfoResponse

Properties

Property	Type	Description
`fee_estimates?`	`Partial`<`Record`<`"bitcoin"` \| `"liquid"`, `FeeEstimate`>>	-
`online`	`boolean`	Whether the Lightning node pays and receives; `false` while it runs in offline mode.
`policy`	`Policy`	-
`quote_id?`	`string` \| `null`	-
`quote_ttl`	`number`	Seconds a `quote_id` stays valid once issued. Min 0
`webhook?`	`WebhookInfo`	-

LightningPolicyResponse

Properties

Property	Type	Description
`max_amount`	`string`	-
`min_amount`	`string`	-
`service_ppm`	`number`	Min 0

OutPoint

On-chain opening-transaction output that funds a swap.

Properties

Property	Type	Description
`txid`	`string`	Opening transaction id.
`vout`	`number`	Opening transaction output index.

Pagination

Properties

Property	Type	Description
`has_next`	`boolean`	-
`limit`	`number`	Min 0
`offset`	`number`	Min 0
`total`	`number`	Min 0

Policy

Properties

Property	Type	Description
`chain`	`Partial`<`Record`<`"bitcoin"` \| `"liquid"`, `ChainPolicyResponse`>>	-
`invoice_expiry`	`number`	Min 0
`lightning`	`LightningPolicyResponse`	-
`network`	`SwapNetwork`	On-chain network for swap operations.
`protocol_version`	`string`	-

RevealClaimRequest

Properties

Property	Type
`source_refund_privkey`	`string`

RevealPreimageRequest

Properties

Property	Type
`preimage`	`string`

SwapListQuery

Filters for GET /v1/swap. They intersect, and all of them apply before limit and offset, so Pagination::total counts what they matched. A filter sent with nothing in it means the same as one left out.

Properties

Property	Type	Description
`created_after?`	`number` \| `null`	Keeps swaps created at or after this unix timestamp, in seconds. Min 0
`created_before?`	`number` \| `null`	Keeps swaps created at or before this unix timestamp, in seconds. Min 0
`error_type?`	`string` \| `null`	Comma-separated cancellation reasons to keep, e.g. `UserCanceled,Timeout`. Only a cancelled swap has one, so this filters out every other swap too.
`is_active?`	`boolean` \| `null`	`true` keeps only active swaps, `false` only finished ones; omit for both.
`limit`	`number`	Page size, at most 100. A larger one is rejected, not clamped. Min 0 Max 100
`max_amount?`	`number` \| `null`	Keeps swaps whose `receive_amount` is at most this many sats. Min 0
`min_amount?`	`number` \| `null`	Keeps swaps whose `receive_amount` is at least this many sats. Min 0
`offset`	`number`	Min 0
`search?`	`string` \| `null`	Keeps swaps where `swap_id`, `payment_hash`, `claim_invoice`, `source_txid`, `dest_txid`, or `user_claim_address` equals this value. The match ignores case but is exact, not a prefix.
`status?`	`string` \| `null`	Comma-separated FSM statuses to keep, e.g. `Claimed,Refunded`.
`swap_type?`	`string` \| `null`	Keeps only swaps of this type: `SwapIn`, `SwapOut`, or `SwapChain`.
`user_id`	`string`	-
`with_create_request?`	`boolean`	`true` carries each swap's `create_request_*` fields as `GET /v1/swap/{id}` does; a page omits them otherwise.

SwapListResponse

Properties

Property	Type
`pagination`	`Pagination`
`swaps`	`SwapState`[]

SwapState

Properties

Property	Type	Description
`base_fee`	`string`	-
`cancel_message?`	`string` \| `null`	-
`claim_invoice?`	`string` \| `null`	-
`create_request_body?`	`string` \| `null`	The `POST /v1/swap` body this swap was created from, verbatim. With the two fields below it lets a client verify the swap's terms against its own signature rather than against this response. Returned by `GET /v1/swap/{id}`, and by the listing under `with_create_request`.
`create_request_signature?`	`string` \| `null`	Hex of the 64-byte Schnorr signature over that request.
`create_request_timestamp?`	`number` \| `null`	-
`created_at`	`number`	Min 0
`dest_asset?`	`string` \| `null`	-
`dest_chain?`	`Chain` \| `null`	-
`dest_claim_pubkey?`	`string` \| `null`	-
`dest_csv?`	`number` \| `null`	Min 0
`dest_refund_privkey?`	`string` \| `null`	-
`dest_refund_pubkey?`	`string` \| `null`	-
`dest_service_blinding_pubkey?`	`string` \| `null`	Liquid: anyswap's blinding pubkey for the destination output.
`dest_txid?`	`string` \| `null`	-
`dest_user_blinding_pubkey?`	`string` \| `null`	Liquid: the user's blinding pubkey for the destination output.
`dest_vout?`	`number` \| `null`	Min 0
`error_type?`	`string` \| `null`	-
`payment_hash`	`string`	-
`preimage?`	`string` \| `null`	-
`protocol_version`	`string`	-
`receive_amount`	`string`	-
`send_amount`	`string`	-
`service_fee`	`string`	-
`source_asset?`	`string` \| `null`	-
`source_chain?`	`Chain` \| `null`	-
`source_claim_privkey?`	`string` \| `null`	-
`source_claim_pubkey?`	`string` \| `null`	-
`source_csv?`	`number` \| `null`	Min 0
`source_refund_pubkey?`	`string` \| `null`	-
`source_service_blinding_pubkey?`	`string` \| `null`	Liquid: anyswap's blinding pubkey for the source output.
`source_txid?`	`string` \| `null`	-
`source_user_blinding_pubkey?`	`string` \| `null`	Liquid: the user's blinding pubkey for the source output.
`source_vout?`	`number` \| `null`	Min 0
`status`	`string`	-
`swap_id`	`string`	-
`swap_type`	`SwapType`	Swap kind. Directions are relative to Lightning: `SwapIn` is on-chain to Lightning, `SwapOut` is Lightning to on-chain, `SwapChain` is on-chain to on-chain across two different chains.
`transitioned_at`	`number`	Min 0
`user_claim_address?`	`string` \| `null`	-
`user_refund_address?`	`string` \| `null`	-

SwapStateUpdate

Properties

Property	Type
`status`	`string`
`swap_id`	`string`

SwapWebhook

Status webhook registered with a swap and fixed for its lifetime. The service POSTs { event: "swap.update", data: { id, status } } to url on every subscribed change. Deliveries are unsigned, unordered, and not guaranteed: treat one as a prompt to read getSwap, not as state.

S bounds statuses; SwapInWebhook and SwapOutWebhook pin it to one direction.

Type Parameters

Type Parameter	Default type
`S` extends `SwapStatus`	`SwapStatus`

Properties

Property	Type	Description
`hash_swap_id?`	`boolean`	Send the SHA256 of the swap id instead of the id itself.
`statuses?`	`S`[]	Statuses to deliver. Omitted or empty delivers every status change.
`url`	`string`	Destination the service posts to, at most 250 characters.

TimeoutResponse

Deadlines this chain enforces as a SwapIn source, in seconds. A swap left in the matching status past its deadline is canceled. SwapOut has no deadline here: once its opening tx confirms, the bound is the dest_csv timelock in blocks.

Properties

Property	Type	Description
`await_claim_key_reveal_message`	`number`	Deadline to reveal the cooperative claim key. Min 0
`await_opening_tx`	`number`	Maximum wait for the opening tx to appear at the swap address and confirm. The claim invoice expiry may end it sooner. Min 0

WebhookInfo

Properties

Property	Type	Description
`enabled`	`boolean`	Whether this node accepts webhook registrations.
`https_required`	`boolean`	Whether a registered url must use https.

Type Aliases

SwapEndpoint

type SwapEndpoint = 
  | {
  asset?: string;
  chain: Chain;
}
  | "lightning";

A swap endpoint: an on-chain asset, or Lightning.

asset is the policy label the server files the asset under in policy.chain[chain].asset, not the on-chain id. It defaults to NATIVE_ASSET, which is the only label the server currently accepts. The id that goes on the wire as source_asset_id / dest_asset_id is a separate value, which the driver reads from the server's policy; destAsset resolves a destination's.

SwapErrorCode

type SwapErrorCode = 
  | "UserCanceled"
  | "Timeout"
  | "TxValidationFailed"
  | "PayInvoiceFailed"
  | "TxBroadcastFailed";

Machine-readable reason a swap reached Canceled, carried by errorCode alongside the human-readable cancelMessage. Each maps to the terminal event that canceled the swap.

UserCanceled: the user aborted the swap.
Timeout: a waiting state's deadline elapsed.
TxValidationFailed (swap-in): two or more deposits paid the exact swap amount, so the service could not tell which to claim.
PayInvoiceFailed (swap-in): the claim invoice payment failed terminally.
TxBroadcastFailed (swap-out): the destination opening tx was never broadcast.

SwapInStatus

type SwapInStatus = 
  | {
  status: "AwaitOpeningTxConfirmation";
}
  | {
  outpoint: OutPoint;
  status: "PayInvoice";
}
  | {
  outpoint: OutPoint;
  preimage: string;
  status: "AwaitClaimKeyRevealMessage";
}
  | {
  outpoint: OutPoint;
  status: "AwaitClaimTxConfirmation";
}
  | {
  outpoint: OutPoint;
  status: "Claimed";
}
  | {
  cancelMessage: string;
  claimPrivkey: string;
  errorCode: SwapErrorCode;
  status: "Canceled";
};

Swap-in lifecycle state, discriminated by status. Each variant carries only the fields available in that state, so narrowing on status exposes them safely. Normal flow: AwaitOpeningTxConfirmation -> PayInvoice -> AwaitClaimKeyRevealMessage -> AwaitClaimTxConfirmation -> Claimed. The server discovers the deposit by watching the swap address, so there is no announcement step and AwaitOpeningTxConfirmation carries no outpoint. AwaitClaimKeyRevealMessage carries the preimage the server obtained by paying the invoice, which the driver checks before revealing the refund key. Canceled is terminal: errorCode is the machine-readable reason, and the server reveals its claimPrivkey; the user finds the deposit by re-deriving the swap address and refunds it.

SwapInWebhook

type SwapInWebhook = SwapWebhook<SwapInStatus["status"]>;

SwapWebhook restricted to the swap-in lifecycle.

SwapOutStatus

type SwapOutStatus = 
  | {
  status: "AwaitClaimInvoicePay";
}
  | {
  status: "OpeningTxBroadcast";
}
  | {
  outpoint: OutPoint;
  status: "AwaitPreimageRevealed";
}
  | {
  outpoint: OutPoint;
  status: "AwaitRefundTxConfirmation";
}
  | {
  outpoint: OutPoint;
  refundPrivkey: string;
  status: "Claimed";
}
  | {
  cancelMessage: string;
  errorCode: SwapErrorCode;
  status: "Canceled";
}
  | {
  outpoint: OutPoint;
  status: "Refunded";
};

Swap-out lifecycle state, discriminated by status. Normal flow: AwaitClaimInvoicePay -> OpeningTxBroadcast -> AwaitPreimageRevealed -> Claimed (the server reveals refundPrivkey for a cooperative keypath claim). If the user never claims: AwaitRefundTxConfirmation -> Refunded. Canceled is terminal.

SwapOutWebhook

type SwapOutWebhook = SwapWebhook<SwapOutStatus["status"]>;

SwapWebhook restricted to the swap-out lifecycle.

SwapStatus

type SwapStatus = 
  | SwapInStatus["status"]
  | SwapOutStatus["status"];

Every status either flow reports, derived from SwapInStatus and SwapOutStatus so it cannot drift from them. Used to filter a swap listing by status.

Variables

NATIVE_ASSET

const NATIVE_ASSET: "native" = "native";

Policy label for a chain's native asset (BTC on Bitcoin, L-BTC on Liquid). The server keys its per-chain asset policy under this label, and execution is single-asset, so it is the only label a swap can name.

On Bitcoin it doubles as the on-chain asset id: source_asset_id is literally "native". On Liquid the id is the asset's 32-byte hex instead, which lives in policy.chain.liquid.asset.native.asset_id. Use destAsset rather than hardcoding this constant as an asset id.

Enumerations​

Chain​

Enumeration Members​

ErrorCode​

Enumeration Members​

SwapNetwork​

Enumeration Members​

SwapType​

Enumeration Members​

Interfaces​

ApiError​

Properties​

AssetPolicyResponse​

Properties​

CancelRequest​

Properties​

ChainPolicyResponse​

Properties​

CreateSwapRequest​

Extends​

Properties​

FeeEstimate​

Properties​

InfoResponse​

Properties​

LightningPolicyResponse​

Properties​

OutPoint​

Properties​

Pagination​

Properties​

Policy​

Properties​

RevealClaimRequest​

Properties​

RevealPreimageRequest​

Properties​

SwapListQuery​

Properties​

SwapListResponse​

Properties​

SwapState​

Properties​

SwapStateUpdate​

Properties​

SwapWebhook​

Type Parameters​

Properties​

TimeoutResponse​

Properties​

WebhookInfo​

Properties​

Type Aliases​

SwapEndpoint​

SwapErrorCode​

SwapInStatus​

SwapInWebhook​

SwapOutStatus​

SwapOutWebhook​

SwapStatus​

Variables​

NATIVE_ASSET​

Enumerations

Chain

Enumeration Members

ErrorCode

Enumeration Members

SwapNetwork

Enumeration Members

SwapType

Enumeration Members

Interfaces

ApiError

Properties

AssetPolicyResponse

Properties

CancelRequest

Properties

ChainPolicyResponse

Properties

CreateSwapRequest

Extends

Properties

FeeEstimate

Properties

InfoResponse

Properties

LightningPolicyResponse

Properties

OutPoint

Properties

Pagination

Properties

Policy

Properties

RevealClaimRequest

Properties

RevealPreimageRequest

Properties

SwapListQuery

Properties

SwapListResponse

Properties

SwapState

Properties

SwapStateUpdate

Properties

SwapWebhook

Type Parameters

Properties

TimeoutResponse

Properties

WebhookInfo

Properties

Type Aliases

SwapEndpoint

SwapErrorCode

SwapInStatus

SwapInWebhook

SwapOutStatus

SwapOutWebhook

SwapStatus

Variables

NATIVE_ASSET