Tunes the check before the wallet:
{ solanaRpcUrl } to simulate Solana transactions on your RPC, { allowContracts: { [chainId]: ["0x…"] } } to accept a venue’s new contract early. false turns it off.Console warnings while you build when your fee isn’t sent or reported, or a swap is never tracked; on unless
NODE_ENV is production or test, false turns them off and true keeps them on.executeAndTrack
Runs a whole swap from aquoteToken: execute, approvals, the swap, your fee, then status polling
to a final state. It works for every execution type and chain, given your own wallet functions or the
wallet add-ons.
Every handler that sends should return every hash it sent, and reject only when nothing was sent.
When something may have gone out and the wallet won’t say, reject with
new SentUnclearError(message, hash?): the swap is then tracked as sent.
Options
Result:
execution, quoteToken (the one /execute returned), txHash, statusRef,
statusTxHash, approvalTxHash, feeTxHash,
feeError (why your fee wasn’t sent or proven, if it wasn’t), finalStatus, and with
sendDeposit on, depositNotSent (why a deposit wasn’t sent: send it yourself).
Errors and resuming. Before anything is sent, it rejects with the underlying error. After that,
it rejects only with an ExecuteAndTrackError (code: FAILED, ABORTED or TIMEOUT) whose
partial holds every hash so far. Keep polling with
getStatus(partial.quoteToken, partial.statusRef, partial.statusTxHash). If partial has no
txHash, signature, signedTransaction or sentUnclear, and your handlers keep the handler rule
above, no swap went out: get a fresh quote. With sentUnclear and no hash, it may have: tell your
user to check their wallet before trying again.
Wallet add-ons
Ready-made handlers with the checks RAVN’s own app makes before a wallet is asked for anything. Each is its own import, so your bundle carries only the ones you use.
The viem handlers switch the wallet to the swap’s chain and check it moved. Every transaction they
send on its own goes with a gas limit, RAVN’s or their own estimate with headroom, and one that won’t
estimate isn’t sent. They
skip an approval the allowance already covers, and stop before one when the wallet can’t also pay
the swap’s gas. Where the wallet and
batch allow, the approval and the swap go in one
confirmation.
The Solana handlers simulate each transaction before the wallet sees it. One they send is sent
again every 2 seconds until it lands at confirmed, for up to 2 minutes.
On Node without a bundler, as an ES module, import from @ravnexchange/sdk/dist/viem.js (or
solana.js, bitcoin.js).
Methods
Each wraps one endpoint with the same fields as the API reference and throwsRavnApiError on failure.
depositFeePayment
depositFeePayment(execution) says what fee to pay beside a DEPOSIT you send yourself: kind
transaction (EVM: send it once the deposit confirms), bitcoin_output or solana_transfer (add
it to the deposit’s own transaction). undefined when there’s none.
recoverStuckFunds
Gets a failed Hinkal swap’s funds back to the paying wallet, checking every step before it’s signed:The check before the wallet
execute (and so executeAndTrack) checks every execution against what your user asked to swap
before you can hand it to a wallet. It throws UnsafeExecutionError unless:
- EVM transactions and approvals go only to contracts RAVN’s venues use, and touch only the input token, up to the input amount;
- no more native coin is sent than the input amount, and none on a token sell;
- RAVN’s fee goes only to RAVN and is at most 1%;
- signatures are of kinds RAVN’s venues use, for the input token, up to the amount;
- a Bitcoin PSBT pays only the deposit, RAVN’s fee and change back to the sender;
- a Solana transaction calls only programs RAVN’s venues use and moves at most the input amount.
With
guard: { solanaRpcUrl }it’s also simulated on your RPC (Agave 2.3 or later), and every transfer out of the user’s accounts must stay within the swap.
getQuote. For a quoteToken quoted elsewhere (say, on your
server), pass it: execute({ quoteToken }, { intent: { inputChainId, inputToken, inputAmount, userAddress } }).
Quote with token addresses, not symbols.
What it can’t see: whether a venue pays out fairly once funds are in its contract, and allowances
the user already gave those contracts. Without a Solana RPC, rely on the wallet’s own simulation. An
UnsafeExecutionError means nothing was sent: get a fresh quote, and tell RAVN if it persists.
Errors
code is the API error code, or NETWORK_ERROR when no response came back.
