RFQ Protocol

A negotiated quote commits live amounts, keys, timeouts, and route-specific construction data before settlement begins. This page defines the wire family that carries those quotes — one family for every route. Served today: the four BTC corridor pairs. The transport for routes whose endpoints both use arkade (arkadeSwapRequest) is specified and joins when served — Asset Swaps covers how that route sources its quote today.

Quote Lifecycle

Beat	What it requires
Discover	Filter accepted solver cards by network, route, amount, and application policy. Discovery advertises capability; it does not prove inventory.
Request terms	Address an encrypted request to one solver, or publish the request and select one sealed bid.
Verify	Check solver identity, route, amounts, expiry, timing, and settlement profile. Derive the contract locally and reject any mismatch.
Commit	Persist the complete recovery record, then perform the route’s first enforceable commitment before `valid_until`.
Settle or recover	Complete the destination action and required claims, or follow the settlement profile’s timeout and refund paths.

Addressed and Published Requests

Mode	Audience	Selection	Status
Addressed (`rfq_request`)	One solver, encrypted to its discovery key	The application selects before requesting terms	Served
Published (`rfq_open`)	Every solver watching the pair	Solvers return sealed bids; the application selects one and closes with an addressed request	Work in progress

Addressed is the shipped path — build against it. Published mode is still in development: no client publisher exists, the reference deployment bids only on Lightning sends, and its payloads are not specified below, deliberately. Pinning rfq_open and rfq_bid field names before an implementation exists would publish a schema that the first working publisher then contradicts. The client work is tracked in ts-sdk#725; once it lands, dropping the transport’s solverPubkey is the entire client change. Neither a request nor a bid locks funds. A bid is signed and attributable but not bonded. The signed quote returned by the selected solver is the binding RFQ message.

Relay

RFQ messages may travel through Nostr relays. Client and solver each dial out; neither needs to accept inbound connections. A relay transports messages but does not select a solver, aggregate quotes, or touch funds.

Kind	Purpose	Encryption
`24859`	Addressed requests, quotes, bids, refusals, and status	NIP-44 to the recipient, addressed by `p` tag
`24860`	Published request	Plaintext, tagged with the canonical market key
`38859`	Replaceable solver advertisement	Unencrypted and indicative only

The negotiation kinds sit in NIP-01’s ephemeral range: relays deliver them to live subscribers and store nothing, so an expired negotiation leaves no public record. The cost is no store-and-forward — a request sent while the solver is offline is dropped, which the client timeout and retry cover. The advertisement is replaceable: standing state a relay keeps the current version of. Kind numbers remain provisional.

Message Family

Every payload carries the envelope {"v": 1, "type": …}.

Message	Direction	Purpose
`rfq_request`	Client → solver	Request executable terms for one route
`rfq_quote`	Solver → client	Return signed, expiring terms
`rfq_refusal`	Solver → client	Decline before settlement exposure exists
`rfq_status_request`	Client → solver	Request best-effort lifecycle state
`rfq_status`	Solver → client	Return state and terminal receipt data
`rfq_open`	Client → many solvers	Publish a request without creating settlement state — work in progress
`rfq_bid`	Solver → client	Return a sealed bid for a published request — work in progress

Addressed payloads are transport-independent. The reference service accepts HTTP and Nostr traffic; clients can implement another transport while preserving the same payloads.

Payload Schemas

Field names below are exact. The reference solver validates a request strictly: an unknown field, a misspelled one, or a missing required one refuses the whole request rather than being ignored — a wrong name and an absent field fail identically. These are the addressed-mode payloads. rfq_open and rfq_bid are work in progress and are not specified here — see Addressed and Published Requests.

Encodings

Kind	Encoding
Public keys (`*_pubkey`)	x-only, 32 bytes, lowercase hex — 64 characters
Scripts (`*_pk_script`)	Taproot scriptPubKey, 34 bytes, lowercase hex
`payment_hash`	`sha256(P)`, 32 bytes, lowercase hex, BOLT11 convention
`claim_packet`	Base64
Amounts	Integers in the base units of their side — sats on every BTC leg
Times (`valid_until`, `*_locktime`, `updated_at`)	Unix seconds
Addresses	Bech32m strings for the network in use

Both scripts commit to ripemd160(sha256(P)), derived locally from payment_hash on each side; the hex on the wire is the sha256 digest alone. Client-supplied keys are x-only. Solver-supplied keys — solver_pubkey, htlc_pubkey, claim_pubkey — may also arrive as 33-byte compressed keys, and the reference client drops the prefix before using them.

Request Envelope

{
  "v": 1,
  "type": "rfq_request",
  "rfq_id": "a1b2c3…9f0e",
  "pair": "arkade:BTC->onchain:BTC",
  "amount_side": "from",
  "amount": 100000,
  "profile": {}
}

Field	Required	Meaning
`v`	Yes	Envelope version; `1`
`type`	Yes	`rfq_request`
`rfq_id`	Yes	Client-chosen negotiation id: 32 random bytes, lowercase hex. Every reply correlates by it
`pair`	Yes	`<from>-><to>`, each leg `<corridor>:<asset>`
`amount_side`	Yes	Which side `amount` fixes: `from` is exact-in, `to` is exact-out
`amount`	Per route	Integer base units of the side named by `amount_side`
`profile`	Yes	Route-specific construction data; the tables below give it per pair

rfq_id is the client’s, not the solver’s — generate it before sending and correlate every reply against it. A reply whose rfq_id differs is a reply to a different negotiation and must not be read as this one’s answer. The BOLT11 send profile is the one route that omits amount: the invoice fixes it, so the request pins amount_side to to and restates nothing.

`arkade:BTC → lightning:BTC`

{
  "v": 1,
  "type": "rfq_request",
  "rfq_id": "a1b2c3…9f0e",
  "pair": "arkade:BTC->lightning:BTC",
  "amount_side": "to",
  "profile": {
    "invoice": "lnbc21u1p…",
    "refund_address": "ark1q…",
    "client_refund_pubkey": "7f3a20…c1d4"
  }
}

Profile field	Meaning
`invoice`	The BOLT11 the solver is asked to pay. Its amount is the quote’s `to_amount`
`refund_address`	The client’s own Arkade address; the covenant refund is pinned to it
`client_refund_pubkey`	The client’s key in the lockup’s `sender` role — bound into every refund-side leaf

`arkade:BTC → onchain:BTC`

{
  "v": 1,
  "type": "rfq_request",
  "rfq_id": "a1b2c3…9f0e",
  "pair": "arkade:BTC->onchain:BTC",
  "amount_side": "to",
  "amount": 100000,
  "profile": {
    "payment_hash": "da5f91…37bc",
    "payout_pubkey": "4e18cc…b902",
    "refund_address": "ark1q…",
    "client_refund_pubkey": "7f3a20…c1d4"
  }
}

Profile field	Meaning
`payment_hash`	`sha256(P)` for the client-generated preimage that opens both contracts
`payout_pubkey`	The client’s Bitcoin L1 key for the HTLC’s claim leaf
`refund_address`	The client’s own Arkade address; the covenant refund is pinned to it
`client_refund_pubkey`	The client’s key in the Arkade lockup’s `sender` role

`lightning:BTC → arkade:BTC`

{
  "v": 1,
  "type": "rfq_request",
  "rfq_id": "a1b2c3…9f0e",
  "pair": "lightning:BTC->arkade:BTC",
  "amount_side": "from",
  "amount": 50000,
  "profile": {
    "payment_hash": "da5f91…37bc",
    "payout_address": "ark1q…",
    "payout_pubkey": "9c02fa…41e8",
    "claim_packet": "3Qk9…=="
  }
}

Profile field	Meaning
`payment_hash`	`sha256(P)` for the client’s own preimage. The solver issues its hold invoice on this hash
`payout_address`	Where the swapped sats land; also the covenant claim’s pinned destination
`payout_pubkey`	The client’s key in the lockup’s `receiver` role, so it can claim without the claim service
`claim_packet`	`P` sealed to the claim service’s key — never to the solver

P never travels in the clear. The solver receives the hash and the sealed packet; it learns the preimage only when a claim publishes it.

`onchain:BTC → arkade:BTC`

{
  "v": 1,
  "type": "rfq_request",
  "rfq_id": "a1b2c3…9f0e",
  "pair": "onchain:BTC->arkade:BTC",
  "amount_side": "from",
  "amount": 100000,
  "profile": {
    "payment_hash": "da5f91…37bc",
    "claim_packet": "3Qk9…==",
    "refund_pubkey": "b7712e…08af",
    "payout_address": "ark1q…",
    "payout_pubkey": "9c02fa…41e8"
  }
}

Profile field	Meaning
`payment_hash`	`sha256(P)` for the client’s own preimage
`claim_packet`	`P` sealed to the claim service’s key
`refund_pubkey`	The client’s Bitcoin L1 key for the HTLC’s refund leaf — its own recovery path
`payout_address`	Where the swapped sats land; the covenant claim’s pinned destination
`payout_pubkey`	The client’s key in the Arkade lockup’s `receiver` role

Routes whose endpoints both use `arkade`

Specified, not served — see Asset Swaps for how this route sources its quote today. The pair string stays coarse and the asset ids ride the profile, mirroring the offer TLV.

{
  "v": 1,
  "type": "rfq_request",
  "rfq_id": "a1b2c3…9f0e",
  "pair": "arkade:BTC->arkade:ASSET",
  "amount_side": "from",
  "amount": 100000,
  "profile": {
    "want_asset": "f121ac…791a0000"
  }
}

Exactly one of want_asset and offer_asset is set per request — the BTC side names no asset. want_asset describes an arkade:BTC->arkade:ASSET request, offer_asset the reverse; each is the hex-serialized asset id.

Quote

{
  "v": 1,
  "type": "rfq_quote",
  "rfq_id": "a1b2c3…9f0e",
  "pair": "arkade:BTC->lightning:BTC",
  "from_amount": 2130,
  "to_amount": 2100,
  "solver_pubkey": "66422c…95d1",
  "valid_until": 1800000900,
  "refund_locktime": 1800277200,
  "profile": {
    "payment_hash": "da5f91…37bc",
    "lockup_address": "ark1q…",
    "receiver_pk_script": "5120a3…7c"
  }
}

rfq_id and pair must equal the request’s. refund_locktime is present on every HTLC-class quote and absent where both endpoints use arkade. The spread between from_amount and to_amount is the complete cost — there is no fee field. The quote profile carries the route’s construction data:

Pair	Quote profile fields
`arkade:BTC → lightning:BTC`	`lockup_address`, `receiver_pk_script`, `payment_hash`
`lightning:BTC → arkade:BTC`	`invoice`, `lockup_address`, `solver_refund_pk_script`, `payment_hash`
`arkade:BTC → onchain:BTC`	`lockup_address`, `receiver_pk_script`, `htlc_pubkey`, `htlc_locktime`, `htlc_address`, `min_confirmations`
`onchain:BTC → arkade:BTC`	`lockup_address`, `solver_refund_pk_script`, `claim_pubkey`, `htlc_locktime`, `htlc_address`, `min_confirmations`

Profile field	Meaning
`lockup_address`	The Arkade lockup — comparison-only, derive it and reject a mismatch
`htlc_address`	The Bitcoin L1 HTLC — comparison-only on the same terms
`receiver_pk_script`	The solver’s claim destination, consumed only to derive the covenant claim key
`solver_refund_pk_script`	The solver’s covenant refund destination on the receive legs
`htlc_pubkey`	The solver’s L1 key for the HTLC’s refund leaf (`arkade:BTC → onchain:BTC`)
`claim_pubkey`	The solver’s L1 key for the HTLC’s claim leaf (`onchain:BTC → arkade:BTC`)
`htlc_locktime`	When the L1 refund leaf opens
`min_confirmations`	Depth the L1 funding must reach before the other side acts; a quote may name 1 to 6
`invoice`	The solver’s hold invoice on the client’s `H` — verify it against that hash before publishing it
`payment_hash`	The swap’s hash. On the BOLT11 send leg it restates the invoice’s, and the client’s own decode stays authoritative

Which of these bind and which are compared is set out in Quote Boundary and, per direction, in Derive, Never Accept.

Refusal

{
  "v": 1,
  "type": "rfq_refusal",
  "rfq_id": "a1b2c3…9f0e",
  "reason": "amount_out_of_range"
}

reason comes from a closed set: unsupported_pair, unsupported_payload, amount_out_of_range, exposure_cap, invoice_expired, quote_conflict, pricing_unavailable. Treat an unrecognized reason as a generic decline — the set may grow, and a refusal is never an error to retry blindly.

Status

{
  "v": 1,
  "type": "rfq_status_request",
  "rfq_id": "a1b2c3…9f0e"
}

{
  "v": 1,
  "type": "rfq_status",
  "rfq_id": "a1b2c3…9f0e",
  "state": "filled",
  "updated_at": 1800001200,
  "profile": {}
}

state is one of the wire states below. Status is best effort: a timeout, a missing response, or an unknown state means unknown, never failed.

Transport Framing

The payloads above are what a transport carries; neither transport changes a field.

Transport	Request	Status
HTTP	`POST /v1/swap` with the request as the body; the reply body is `rfq_quote`, or `rfq_refusal` with a 4xx status	`GET /v1/rfq/<rfq_id>`; `404` means no status
Nostr	Kind `24859` event, NIP-44-encrypted to the solver’s discovery key, `p`-tagged with it	The same kind, carrying `rfq_status_request`

A 4xx carrying an rfq_refusal body is the refusal path, so the status code alone cannot decide whether to read the body — parse it, and fall back to the status code only when the body is not a payload of this family. On Nostr the client signs with a transport key it may generate fresh per negotiation; nothing in the protocol needs a stable client identity, since the quote binds to the contract rather than to who asked for it. Replies arrive on a subscription filtered to that key and are correlated by rfq_id.

RFQ Wire States

State	Meaning
`refused`	Solver declined before any settlement exposure existed
`quoted`	Binding terms issued, awaiting the profile-specific commitment
`expired`	`valid_until` passed without a conforming in-time commitment
`funded`	The settlement contract is funded
`filling`	The solver’s destination action is in flight
`filled`	The destination action completed and claims remain
`settled`	Both sides completed and receipts are available
`refunded`	A refund path executed
`stuck`	Exposure exists and progress requires operator attention

The client-side RfqSwapManager monitors funded swaps from chain evidence with its own states rather than consuming these wire states; its failed outcome is client-side reporting.

Quote Boundary

Economic commitments stay at the top level. Settlement construction data stays inside profile.

Quote data	Client treatment
`rfq_id`, `pair`	Must match the request and selected route
`from_amount`, `to_amount`	Binding amounts; their spread contains the fee
`solver_pubkey`	Binding settlement key
`valid_until`	Deadline for beginning the profile-specific commitment
`refund_locktime`	Binding timeout when the profile carries it — the client refund deadline on send routes, the solver refund horizon on receive routes
Address, script, or contract fields in `profile`	Comparison-only; derive locally and reject a mismatch

Profile fields are also checked against client-owned inputs such as an invoice, payment hash, destination, and network. Recheck time-sensitive conditions immediately before value moves.

Transport Requirements

Regardless of transport implementation:

reconnect after both connection errors and clean closes;
restore live subscriptions on a new connection;
bound and persist or reject outbound events queued while disconnected;
correlate every response with the expected RFQ identifier and route;
treat a status timeout as unknown, not failed.

Contract and destination-network evidence remain authoritative.

Persistence Requirements

Persist recovery data before the route’s first enforceable commitment. At a minimum, retain:

route;
swap identifier or RFQ identifier;
encoded terms and verified solver identity;
derived script or contract data;
funding transaction identifier;
expiry and refund timing;
wallet-owned key or preimage derivation data;
destination-network identifiers required for reconciliation.

Some generated secrets do not exist anywhere else. Losing them can remove an interactive refund or claim path.

Current Boundary

The reference RFQ service implements the four BTC corridor profiles but is closed source. See Implementation Status before building against the wire protocol.

Understand Intents

Build with Intents

Earn Fees

Reference

Quote Lifecycle

Addressed and Published Requests

Relay

Message Family

Payload Schemas

Encodings

Request Envelope

`arkade:BTC → lightning:BTC`

`arkade:BTC → onchain:BTC`

`lightning:BTC → arkade:BTC`

`onchain:BTC → arkade:BTC`

Routes whose endpoints both use `arkade`

Quote

Refusal

Status

Transport Framing

RFQ Wire States

Quote Boundary

Transport Requirements

Persistence Requirements

Current Boundary

​Quote Lifecycle

​Addressed and Published Requests

​Relay

​Message Family

​Payload Schemas

​Encodings

​Request Envelope

​arkade:BTC → lightning:BTC

​arkade:BTC → onchain:BTC

​lightning:BTC → arkade:BTC

​onchain:BTC → arkade:BTC

​Routes whose endpoints both use arkade

​Quote

​Refusal

​Status

​Transport Framing

​RFQ Wire States

​Quote Boundary

​Transport Requirements

​Persistence Requirements

​Current Boundary

Quote Lifecycle

Addressed and Published Requests

Relay

Message Family

Payload Schemas

Encodings

Request Envelope

`arkade:BTC → lightning:BTC`

`arkade:BTC → onchain:BTC`

`lightning:BTC → arkade:BTC`

`onchain:BTC → arkade:BTC`

Routes whose endpoints both use `arkade`

Quote

Refusal

Status

Transport Framing

RFQ Wire States

Quote Boundary

Transport Requirements

Persistence Requirements

Current Boundary