> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravn.exchange/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Swap 1 ETH to SOL end to end.

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](/tools/get-api-key) first if you can, it
takes 30 seconds, quadruples your rate limit, and gets your project on RAVN's radar.

<Tip>
  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](/sandbox-mode).
</Tip>

<Steps>
  <Step title="Get a quote">
    Price the swap. You get back the best route across every venue plus an opaque `quoteToken`.

    ```bash theme={null}
    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"
      }'
    ```
  </Step>

  <Step title="Execute">
    Hand the `quoteToken` back. RAVN returns how to complete the swap, tagged by `executionType`.

    ```bash theme={null}
    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": "..." }
    ```
  </Step>

  <Step title="Complete it">
    Branch on `executionType`. This is the entire client-side contract.

    ```js theme={null}
    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;
    }
    ```

    <Warning>
      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](/execution-types#the-approval-step).
    </Warning>

    <Tip>
      On JS/TS, [`@ravnexchange/sdk`](/sdks/core)'s `executeAndTrack` sequences this correctly for you,
      given your own sign/send functions, instead of hand-rolling the switch above.
    </Tip>
  </Step>

  <Step title="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`).

    ```bash theme={null}
    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](/api-reference/status#settlement).
  </Step>
</Steps>

<Note>
  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.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.