Quickstart

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.

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", "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(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.

Track it

Poll status with the statusRef from execute, or the statusRef from submit-signature.

curl -s "https://app.ravn.exchange/api/v1/status?quoteToken=<token>&ref=<statusRef>"
# returns { "status": "pending" | "processing" | "success" | "expired" | "refunded" | "failed" }
# terminal: success, refunded, failed. Keep polling on expired; a refund is still due.

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.

Overview

Guides

API Reference

AI Agents