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

# Test: Swaps

> Test token swap functionality in the Yativo Crypto sandbox

## Overview

Test the full swap lifecycle — getting quotes and executing cross-chain or same-chain token swaps — without spending real funds.

**Sandbox base URL:** `https://crypto-sandbox.yativo.com/api/v1/`

<Note>
  Swap rates in the sandbox are simulated. They reflect approximate market conditions but are not live market prices.
</Note>

***

## Step 1 — Get a Swap Quote

Request a price quote before executing. The quote includes the expected output amount, rate, and fees.

```
POST https://crypto-sandbox.yativo.com/api/v1/swap/quote
```

<ParamField body="from_chain" type="string" required>
  Source blockchain: `solana`, `ethereum`, `base`, `polygon`, etc.
</ParamField>

<ParamField body="from_ticker" type="string" required>
  Source token ticker: `USDC_SOL`, `ETH`, `SOL`, etc.
</ParamField>

<ParamField body="to_chain" type="string" required>
  Destination blockchain. Can be the same as `from_chain` for same-chain swaps.
</ParamField>

<ParamField body="to_ticker" type="string" required>
  Destination token ticker: `USDC_ETH`, `USDC_SOL`, etc.
</ParamField>

<ParamField body="amount" type="string" required>
  Input amount in the source token's native units, e.g. `"100.00"`.
</ParamField>

<ParamField body="from_address" type="string" required>
  Source wallet address sending the funds.
</ParamField>

<ParamField body="to_address" type="string" required>
  Destination wallet address to receive the swapped funds.
</ParamField>

<CodeGroup>
  ```bash USDC Solana → USDC Ethereum (cross-chain) theme={null}
  curl -X POST 'https://crypto-sandbox.yativo.com/api/v1/swap/quote' \
    -H 'Authorization: Bearer YOUR_SANDBOX_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
      "sourceAsset": "USDC_SOL",
      "destinationAsset": "ETH_Base",
      "amount": "10"
    }'
  ```

  ```bash Same-chain swap theme={null}
  curl -X POST 'https://crypto-sandbox.yativo.com/api/v1/swap/quote' \
    -H 'Authorization: Bearer YOUR_SANDBOX_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
      "sourceAsset": "USDC_SOL",
      "destinationAsset": "SOL",
      "amount": "50"
    }'
  ```
</CodeGroup>

```json Response — Quote theme={null}
{
  "status": "success",
  "data": {
    "quote_id": "qte_01HX9KZMB3F7VNQP8R2WDGT4EG",
    "from_chain": "solana",
    "from_ticker": "USDC_SOL",
    "from_amount": "10",
    "to_chain": "base",
    "to_ticker": "ETH_Base",
    "to_amount": "0.00284",
    "exchange_rate": "0.000284",
    "fee": "0.05",
    "fee_ticker": "USDC",
    "price_impact": "0.01",
    "quote_valid_until": "2026-03-28T11:02:00Z",
    "estimated_execution_time_seconds": 120
  }
}
```

<Warning>
  Quotes expire quickly (typically 60–120 seconds). If the quote expires before you execute, request a new one.
</Warning>

***

## Step 2 — Execute the Swap

Execute a swap using a previously obtained quote ID.

```
POST https://crypto-sandbox.yativo.com/api/v1/swap/execute
```

<ParamField body="quote_id" type="string" required>
  The quote ID obtained from `POST /swap/quote`.
</ParamField>

<ParamField body="from_asset_id" type="string" required>
  The asset ID of the source wallet to deduct funds from.
</ParamField>

<ParamField body="to_address" type="string" required>
  Destination wallet address to receive the swapped tokens.
</ParamField>

```bash Execute swap theme={null}
curl -X POST 'https://crypto-sandbox.yativo.com/api/v1/swap/execute' \
  -H 'Authorization: Bearer YOUR_SANDBOX_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "quote_id": "qte_01HX9KZMB3F7VNQP8R2WDGT4EG",
    "from_asset_id": "ast_01HX9KZMB3F7VNQP8R2WDGT4E6",
    "to_address": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
  }'
```

<ResponseExample>
  ```json Swap Initiated theme={null}
  {
    "status": "success",
    "message": "Swap initiated successfully",
    "data": {
      "swap_id": "swp_01HX9KZMB3F7VNQP8R2WDGT4EH",
      "quote_id": "qte_01HX9KZMB3F7VNQP8R2WDGT4EG",
      "from_chain": "solana",
      "from_ticker": "USDC_SOL",
      "to_chain": "base",
      "to_ticker": "ETH_Base",
      "from_amount": "10",
      "to_amount": "0.00284",
      "status": "pending",
      "from_tx_hash": "5KgF7hJ2mN4pQ8rT9vX1yC3bA6wD0eG2jL5nP8sU1z4",
      "created_at": "2026-03-28T11:01:00Z"
    }
  }
  ```

  ```json Quote Expired theme={null}
  {
    "success": false,
    "error": "Quote has expired. Please request a new quote."
  }
  ```
</ResponseExample>

***

## Step 3 — Check Swap History

Retrieve the history of your swaps.

```
GET https://crypto-sandbox.yativo.com/api/v1/swap/history
```

<ParamField query="limit" type="integer">
  Max results to return. Defaults to `20`.
</ParamField>

<ParamField query="offset" type="integer">
  Records to skip for pagination. Defaults to `0`.
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `pending`, `completed`, `failed`.
</ParamField>

```bash cURL theme={null}
curl -X GET 'https://crypto-sandbox.yativo.com/api/v1/swap/history?limit=10&status=completed' \
  -H 'Authorization: Bearer YOUR_SANDBOX_TOKEN'
```

```json Response theme={null}
{
  "success": true,
  "data": [
    {
      "swap_id": "swp_01HX9KZMB3F7VNQP8R2WDGT4EH",
      "from_ticker": "USDC_SOL",
      "from_chain": "solana",
      "from_amount": "10",
      "to_ticker": "ETH_Base",
      "to_chain": "base",
      "to_amount": "0.00284",
      "status": "completed",
      "created_at": "2026-03-28T11:01:00Z"
    }
  ]
}
```

***

## Swap Status Values

| Status       | Description                                           |
| ------------ | ----------------------------------------------------- |
| `pending`    | Swap submitted, awaiting processing.                  |
| `processing` | Swap in progress — tokens are being exchanged.        |
| `completed`  | Swap completed. Destination tokens credited.          |
| `failed`     | Swap failed. Source tokens returned (minus gas fees). |

***

## Testing Scenarios

<Accordion title="Test with an expired quote">
  Wait 60–120 seconds after getting a quote, then try to execute it. Your application should receive an error and re-request a fresh quote.
</Accordion>

<Accordion title="Test insufficient balance">
  Request a quote for more than your available balance, then try to execute it. Verify your application handles the `INSUFFICIENT_BALANCE` error.
</Accordion>

<Tip>
  After a swap completes, verify the balance update by calling `POST /assets/get-user-assets`. The source asset balance should decrease and the destination asset balance should increase.
</Tip>