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: Lightning send and receive, onchain send, and asset swaps whose solver card names a relay. The open-source reference solver, intent-solver, serves them. An asset card without a relay advertises only a feed, and the client prices those swaps itself (Asset Swaps). See Implementation Status for what each deployment serves.

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. The client work is tracked in ts-sdk#725. 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`	The solver’s signed card, `d`-tagged with the network (Cards over Nostr)	Plaintext, signed by `discovery_pubkey`; advisory

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: the swap client gives up after 30 seconds, and the app can request again. The card kind is addressable: a relay keeps only the current card per solver and network. 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’s request schemas are .strict(): an unknown field, a misspelled one, or a missing required one refuses the whole request with unsupported_payload. A wrong name and an absent field fail identically. Responses are the reverse: a client ignores response fields it does not know, so a solver can add one without a version change. 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	Base units of their side: sats on every BTC leg. See below
Times (`valid_until`, `*_locktime`, `updated_at`)	Unix seconds
Addresses	Bech32m strings for the network in use

Amounts depend on the route:

Asset routes take a canonical decimal string only: ASCII digits, with no sign, decimal point, exponent, or leading zero.
BTC corridor routes take a request amount as a canonical decimal string or a JSON integer up to 2^53 − 1, and a solver must accept both. @arkade-os/swap sends a string. Send a quote’s amounts as JSON integers: the client reads both forms, but clients before 0.1 refuse a string BTC amount in a quote.

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) 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 is a wire prefix (`arkade`, `lightning`, or `onchain`), a colon, and the asset: `BTC` or a 68-hex asset id. This is the `v: 1` wire spelling, and it takes no CAIP-19 ids: the swap client maps each route endpoint to a leg before it sends the request
`amount_side`	Yes	Which side `amount` fixes: `from` is exact-in, `to` is exact-out
`amount`	Per route	Base units of the side named by `amount_side`, encoded as in Encodings
`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. A quote echoes the fixed side exactly. A from request must come back with from_amount equal to amount, and a to request with to_amount equal to amount; on the BOLT11 send, to_amount must equal the invoice amount. The client refuses any other quote as a quote for a different trade.

`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 path

`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 onchain key for the HTLC’s claim path
`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"
  }
}

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 the lockup itself
`claim_packet`	Optional. `P` sealed to a key the client chooses, never to the solver’s. Default clients omit it, and an empty string is refused

P never travels in the clear. The solver receives the hash, plus the sealed packet only when the client sends one; it learns the preimage only when a claim publishes it. A client that sends no packet must claim the lockup itself.

Routes whose endpoints both use `arkade`

The swap client sends this request to any asset card that names a relay and a discovery key, and intent-solver answers it for the markets in its ASSET_MARKETS setting. The pair names the asset: each asset leg is arkade: followed by the asset id as 68 lowercase hex characters, and a BTC leg is arkade:BTC. The profile names the client’s position in the swap contract.

{
  "v": 1,
  "type": "rfq_request",
  "rfq_id": "a1b2c3…9f0e",
  "pair": "arkade:BTC->arkade:f121ac…791a0000",
  "amount_side": "from",
  "amount": "100000",
  "profile": {
    "maker_pk_script": "512082…3dea",
    "maker_public_key": "cc8a4b…c115"
  }
}

Profile field	Meaning
`maker_pk_script`	The client’s Taproot scriptPubKey, 34 bytes: the covenant’s `makerWP` with its `5120` prefix. The fill must pay this script
`maker_public_key`	The client’s x-only key: the `user` signer of the `cancel` path

maker_* names a position in the contract, not a role — see The maker Fields. Amounts on these routes are canonical decimal strings. The quote carries no refund_locktime, because neither fulfill nor cancel has a timelock.

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…",
    "refund_without_receiver_delay": 612864,
    "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. An asset quote can also carry a top-level carrier_sats: the dust sats an asset deposit sits on. The amounts already include it, so it is not a fee. The quote profile carries the route’s construction data:

Pair	Quote profile fields
Pay via Lightning	`lockup_address`, `receiver_pk_script`, `payment_hash`, `refund_without_receiver_delay`
Receive via Lightning	`invoice`, `lockup_address`, `solver_refund_pk_script`, `payment_hash`
Pay via Bitcoin	`lockup_address`, `receiver_pk_script`, `htlc_pubkey`, `htlc_locktime`, `htlc_address`, `min_confirmations`, and optionally `refund_without_receiver_delay`
Both endpoints use `arkade`	`offer_address`, `offer_pk_script`

Profile field	Meaning
`lockup_address`	The Arkade lockup. Comparison-only: derive it and reject a mismatch
`htlc_address`	The onchain 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 Lightning receive
`refund_without_receiver_delay`	The delay, in seconds, that the client compiles into the lockup’s `unilateralRefundWithoutReceiver` path. Required on Pay via Lightning. Optional on Pay via Bitcoin: the client binds it when present, and without it uses `claimDelay` + 4096 seconds. The client refuses a value below its derived `claimDelay`, not a multiple of 512, or above `0xffff × 512`. On the Lightning send it also refuses one shorter than the time left until `refund_locktime`
`offer_address`, `offer_pk_script`	The swap contract the client funds when both endpoints use `arkade`. Comparison-only on the same terms
`htlc_pubkey`	The solver’s onchain key for the HTLC’s refund path (Pay via Bitcoin)
`htlc_locktime`	When the onchain refund path opens
`min_confirmations`	Depth the onchain 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, rate_limited. Treat an unrecognized reason as a generic decline. The set may grow, and a refusal is never an error to retry blindly. A refusal can also carry detail fields: error_code, from a second closed set (for example invoice_wrong_network or invoice_cltv_too_large), and field, actual, expected, limit, and unit (blocks, characters, or sats). They explain the refusal; they do not change how to handle it.

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. Receipts appear only in settled: preimage on corridor routes, fill_txid on asset routes. Status is best effort: a timeout, a missing response, or an unknown state means unknown, never failed. For an rfq_id it does not know, the reference solver answers with an rfq_refusal on Nostr and a 404 on HTTP, and the reference client reads both as “no status”.

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. The example below sends an arkade:BTC → lightning:BTC request over Nostr by hand and prints the reply. @arkade-os/swap does all of this for you; the example is for a client in another stack. Take the relay and the solver key from the solver’s card. Install the one dependency:

pnpm add nostr-tools

import { finalizeEvent, generateSecretKey, getPublicKey, nip44, SimplePool } from 'nostr-tools'
import { bytesToHex } from 'nostr-tools/utils'

const RELAY = 'wss://<relay>' // a relay from the solver card's transports
const SOLVER_PUBKEY = '<64-hex discovery_pubkey>' // the solver card's discovery_pubkey
const INVOICE = '<BOLT11 invoice>' // the invoice to pay
const REFUND_ADDRESS = '<your Arkade address>'
const CLIENT_REFUND_PUBKEY = '<your 64-hex x-only public key>'

const secretKey = generateSecretKey() // a fresh transport key for this negotiation
const conversationKey = nip44.v2.utils.getConversationKey(secretKey, SOLVER_PUBKEY)
const rfqId = bytesToHex(crypto.getRandomValues(new Uint8Array(32)))
const pool = new SimplePool()

// Subscribe before you publish: relays keep no ephemeral replies for late subscribers.
const reply = new Promise((resolve) => {
  pool.subscribeMany([RELAY], { kinds: [24859], authors: [SOLVER_PUBKEY], '#p': [getPublicKey(secretKey)] }, {
    onevent(event) {
      const payload = JSON.parse(nip44.v2.decrypt(event.content, conversationKey))
      if (payload.rfq_id === rfqId) resolve(payload)
    },
  })
})

const request = {
  v: 1,
  type: 'rfq_request',
  rfq_id: rfqId,
  pair: 'arkade:BTC->lightning:BTC',
  amount_side: 'to',
  profile: { invoice: INVOICE, refund_address: REFUND_ADDRESS, client_refund_pubkey: CLIENT_REFUND_PUBKEY },
}
const event = finalizeEvent({
  kind: 24859,
  created_at: Math.floor(Date.now() / 1000),
  tags: [['p', SOLVER_PUBKEY]],
  content: nip44.v2.encrypt(JSON.stringify(request), conversationKey),
}, secretKey)
await Promise.any(pool.publish([RELAY], event))

console.log(await reply) // an rfq_quote, or an rfq_refusal such as invoice_expired
pool.close([RELAY])

A real client also needs a timeout: the solver may be offline, and the relay drops a request that no one receives.

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 needs manual action on the solver side

settled, refused, expired, refunded, and stuck are terminal. On asset routes the fill pays both sides in one transaction, so the reference solver reports settled with no filled step, and it reports a quote that expired unfunded as refused. The swap client monitors funded swaps from chain evidence and reports its own outcomes 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

@arkade-os/swap keeps the recovery record below in the repository the app gives it. A client in another stack must persist it 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.

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`

Routes whose endpoints both use `arkade`

Quote

Refusal

Status

Transport Framing

RFQ Wire States

Quote Boundary

Transport Requirements

Persistence Requirements

​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

​Routes whose endpoints both use arkade

​Quote

​Refusal

​Status

​Transport Framing

​RFQ Wire States

​Quote Boundary

​Transport Requirements

​Persistence Requirements

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`

Routes whose endpoints both use `arkade`

Quote

Refusal

Status

Transport Framing

RFQ Wire States

Quote Boundary

Transport Requirements

Persistence Requirements