Quickstart - RAVN

Four calls, always in the same order: quote, execute, complete, then status. Every call below works as-is with no API key. But get a free key first if you can, it takes 30 seconds, quadruples your rate limit, and gets your project on RAVN’s radar.

Want to run this whole flow without moving real funds? Add sandbox: true to the quote in step 1 and every later call sees it automatically. See Sandbox Mode.

Get a quote

Price the swap. You get back the best route across every venue plus an opaque quoteToken.

curl -s -X POST https://app.ravn.exchange/api/v1/quote \
  -H 'content-type: application/json' -d '{
    "inputChainId": 1,
    "outputChainId": -2,
    "inputToken": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
    "outputToken": "So11111111111111111111111111111111111111112",
    "inputAmount": "1000000000000000000",
    "userAddress": "0xYourUser",
    "destinationAddress": "SoYourUser"
  }'

Execute

Hand the quoteToken back. RAVN returns how to complete the swap, tagged by executionType.

curl -s -X POST https://app.ravn.exchange/api/v1/execute \
  -H 'content-type: application/json' \
  -d '{ "quoteToken": "<from step 1>" }'
# returns { "executionType": "DEPOSIT", "quoteToken": "...", "deposit": { "address": "...", "amount": "..." }, "statusRef": "..." }

Complete it

Branch on executionType. This is the entire client-side contract.

switch (res.data.executionType) {
  case "TRANSACTION": {
    // Selling an ERC-20? `approval` is present when the token still needs an allowance.
    // It must be MINED before the swap; broadcasting both together reverts.
    if (res.data.approval) {
      const hash = await wallet.sendTransaction(res.data.approval);
      await wallet.waitForTransactionReceipt({ hash });
    }
    await wallet.sendTransaction(res.data.transaction);
    break;
  }
  case "SIGNATURE": {
    // Gasless still needs an allowance, or the order never fills, silently.
    if (res.data.approval) {
      const hash = await wallet.sendTransaction(res.data.approval);
      await wallet.waitForTransactionReceipt({ hash });
    }
    const sig = await wallet.signTypedData(res.data.typedData);
    await submitSignature(res.data.quoteToken, sig);
    break;
  }
  case "DEPOSIT":     await wallet.send(res.data.deposit.address, res.data.deposit.amount); break;
}

Skipping the approval wait is the most common integration failure. The swap spends your tokens via transferFrom, so if the allowance is not yet mined it reverts and the user loses the gas. Wait for the receipt, not just the broadcast. Native-coin sells and already-approved tokens omit approval entirely.It appears on SIGNATURE too: gasless venues still pull tokens via transferFrom, and skipping it there is quieter and worse: the order is accepted and never fills, with no error. See Execution types.

On JS/TS, @ravnexchange/sdk’s executeAndTrack sequences this correctly for you, given your own sign/send functions, instead of hand-rolling the switch above.

Track it

Poll status with the quoteToken that execute returned (not the one from step 1), and as ref: the statusRef from execute (DEPOSIT, and TRANSACTION when present), the statusRef from submit-signature (SIGNATURE), or otherwise the transaction hash you broadcast (TRANSACTION).

curl -s -X POST https://app.ravn.exchange/api/v1/status \
  -H 'content-type: application/json' \
  -d '{ "quoteToken": "<from execute>", "ref": "<statusRef or tx hash>" }'
# returns { "status": "pending" | "processing" | "success" | "expired" | "refunded" | "failed" }
# terminal: success, refunded, failed. Keep polling on expired; a refund is still due.

Poll every swap to a terminal state. That poll is what marks the swap settled in RAVN’s ledger, and only settled swaps count toward a fee payout. See Settlement.

Amounts are strings in the token’s smallest unit. Native coin uses the sentinel 0xEeee...EEeE. The quoteToken is opaque, so never parse it. It expires, so re-quote if it goes stale.