wavecli sendPrepareSend
PrepareSend validates and previews an outbound payment without moving funds. The response carries a short-lived send_intent_id that must be consumed by Send.
Endpoints
rpc PrepareSend(PrepareSendRequest) returns (PrepareSendResponse)POST/v1/wallet/prepare-sendExamples
wavecli send lnbcrt250u1p3xyz...truncated --note "coffee run" --forcewavecli send lnbcrt250u1p3xyz...truncated --note "coffee run" --forceconn, err := grpc.NewClient("localhost:10029",
grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
log.Fatal(err)
}
defer conn.Close()
client := wavewalletrpc.NewWalletServiceClient(conn)
ctx := context.Background()
req := &wavewalletrpc.PrepareSendRequest{
Invoice: "lnbcrt250u1p3xyz...truncated",
Note: "coffee run",
}
resp, err := client.PrepareSend(ctx, req)
if err != nil {
log.Fatal(err)
}
fmt.Println(resp)import grpc
import wallet_pb2
import wallet_pb2_grpc
channel = grpc.insecure_channel('localhost:10029')
stub = wallet_pb2_grpc.WalletServiceStub(channel)
request = wallet_pb2.PrepareSendRequest(
invoice="lnbcrt250u1p3xyz...truncated",
note="coffee run",
)
response = stub.PrepareSend(request)
print(response)const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const packageDefinition = protoLoader.loadSync('wallet.proto');
const { wavewalletrpc } = grpc.loadPackageDefinition(packageDefinition);
const client = new wavewalletrpc.WalletService(
'localhost:10029',
grpc.credentials.createInsecure(),
);
const request = {
"invoice": "lnbcrt250u1p3xyz...truncated",
"note": "coffee run"
};
// Calls wavewalletrpc.WalletService.PrepareSend.
client.prepareSend(request, (err, response) => {
if (err) throw err;
console.log(response);
});curl -X POST http://localhost:10031/v1/wallet/prepare-send \
-H 'Content-Type: application/json' \
-d '{"invoice":"lnbcrt250u1p3xyz...truncated","note":"coffee run"}'const res = await fetch('http://localhost:10031/v1/wallet/prepare-send', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
"invoice": "lnbcrt250u1p3xyz...truncated",
"note": "coffee run"
}),
});
const prepareSendResponse = await res.json();RequestPrepareSendRequest
PrepareSendRequest describes the outbound payment to validate and preview via WalletService.PrepareSend, before any funds move.
| Field | Type | Description |
|---|---|---|
invoiceoneof destination | string | invoice is a BOLT-11 Lightning invoice. The daemon pays it via its owned swap subsystem; the swap server picks same-Ark p2p vs real Lightning transparently. |
onchain_addressoneof destination | string | onchain_address is a bech32 onchain destination. The daemon submits a LeaveVTXOs request covering amt_sat plus fees. |
amt_sat | uint64 | amt_sat is required for onchain sends. For onchain sends amt_sat must be strictly positive unless sweep_all is set, in which case it must be zero. For invoice sends amt_sat is ignored: v1 requires an amount-bearing BOLT-11 invoice; amountless invoices are rejected at the wallet layer until plumbing for caller-supplied amounts lands in the swap subserver. |
note | string | note is an optional caller-supplied label persisted alongside the entry. It is never interpreted by the daemon. |
max_fee_sat | uint64 | max_fee_sat is the optional caller cap on routing or sweep fees. Zero means use daemon defaults. |
sweep_all | bool | sweep_all signals an explicit wallet-emptying onchain send: every live VTXO is swept to the destination, less fees. The caller must set amt_sat = 0 when this flag is true and a strictly positive amt_sat otherwise. This makes "drain the wallet" structurally distinct from "amt_sat defaulted to zero" so a typo cannot empty the wallet by accident. Ignored on the invoice path. |
ResponsePrepareSendResponse
PrepareSendResponse is the preview of a prepared send: the single-use intent token plus the amount, fee, rail, and quote detail a caller should confirm before calling Send.
| Field | Type | Description |
|---|---|---|
send_intent_id | string | send_intent_id is a short-lived, single-use token consumed by Send. |
amount_sat | int64 | amount_sat is the destination principal amount. |
expected_fee_sat | int64 | expected_fee_sat is meaningful only when fee_known is true. |
fee_known | bool | fee_known is false when a required remote quote API is missing. |
expected_total_outflow_sat | int64 | expected_total_outflow_sat is meaningful only when total_outflow_known is true. |
total_outflow_known | bool | total_outflow_known is false when the final outflow depends on a remote quote that is not available yet. |
rail | SendRail | rail is the expected settlement rail for this prepared send. Onchain prepares always return SEND_RAIL_ONCHAIN. Invoice prepares map the swap quote settlement type when a remote quote is available; when no quote is available (LOCAL_ONLY) or the quote does not distinguish same-Ark from Lightning, the value is SEND_RAIL_OFFCHAIN_UNKNOWN until Send starts. |
quote_status | SendQuoteStatus | quote_status describes how complete the prepare-time quote is. Invoice sends: COMPLETE when every amount and fee is backed by a swap remote quote; LOCAL_ONLY when the invoice parsed locally but the swap quote API was unavailable. Onchain sends: COMPLETE when waverpc.EstimateFee returned a binding operator quote; LOCAL_ONLY when only a local fee floor could be computed. |
destination_summary | string | destination_summary is a short display string suitable for CLI and UI confirmation prompts. |
invoice_description | string | invoice_description is the BOLT-11 description when present. |
payment_hash | string | payment_hash is the invoice payment hash when available. |
expires_at_unix | int64 | expires_at_unix is the unix timestamp after which Send rejects the prepared intent. |
selected_outpoints | repeated string | selected_outpoints is populated for onchain sends so Send can spend exactly the VTXO set previewed to the user. |
warning | string | warning carries a concise human-facing caveat for local-only previews. |
credit_preview | CreditPreview | credit_preview is populated when the invoice send will or can use sat-native server credits. |
SendRailenum
SendRail identifies the expected settlement rail for a prepared send.
| Name | Number | Description |
|---|---|---|
SEND_RAIL_UNSPECIFIED | 0 | SEND_RAIL_UNSPECIFIED is the proto zero value used when no rail has been determined. |
SEND_RAIL_OFFCHAIN_UNKNOWN | 1 | SEND_RAIL_OFFCHAIN_UNKNOWN is used when the wallet can parse the invoice locally but the swapserver has not supplied a quote that distinguishes same-Ark settlement from Lightning settlement. |
SEND_RAIL_IN_ARK | 2 | SEND_RAIL_IN_ARK is same-Ark peer-to-peer settlement, where the payment never touches Lightning. |
SEND_RAIL_LIGHTNING | 3 | SEND_RAIL_LIGHTNING is settlement over the real Lightning network. |
SEND_RAIL_ONCHAIN | 4 | SEND_RAIL_ONCHAIN is an on-chain send via a cooperative leave to the destination address. |
SEND_RAIL_CREDIT | 5 | SEND_RAIL_CREDIT is settlement drawn from the wallet's server-side credit balance. |
SEND_RAIL_MIXED | 6 | SEND_RAIL_MIXED is settlement that combines credit with the normal vHTLC path. |
SendQuoteStatusenum
SendQuoteStatus describes how complete the prepare-time quote is.
| Name | Number | Description |
|---|---|---|
SEND_QUOTE_STATUS_UNSPECIFIED | 0 | SEND_QUOTE_STATUS_UNSPECIFIED is the proto zero value; quote completeness was not reported. |
SEND_QUOTE_STATUS_COMPLETE | 1 | SEND_QUOTE_STATUS_COMPLETE means every user-visible amount and fee field is backed by a remote quote. |
SEND_QUOTE_STATUS_LOCAL_ONLY | 2 | SEND_QUOTE_STATUS_LOCAL_ONLY means the wallet performed local validation and selection but one or more remote quote APIs are not available yet. |
CreditPreviewmessage
CreditPreview describes how server-side sat-native credits factor into a prepared send. It is populated on PrepareSendResponse when the invoice send will or can draw on credits.
| Field | Type | Description |
|---|---|---|
must_use_credit | bool | must_use_credit is true when the invoice amount cannot be represented by the normal vHTLC path and the send must be settled from the credit balance. |
credit_applied_sat | uint64 | credit_applied_sat is the credit balance in satoshis the quote expects to reserve for this send. |
credit_shortfall_sat | uint64 | credit_shortfall_sat is the additional credit in satoshis needed before this payment can be admitted. |
credit_topup_sat | uint64 | credit_topup_sat is the Ark top-up amount in satoshis required to cover the shortfall. It is rounded up and dust-limited by the server. |
ark_funding_sat | uint64 | ark_funding_sat is the amount in satoshis the client must still fund through the normal vHTLC path. |