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

# Transaction Management

> Save and track the status of swap transactions

## POST /leokit/save-transaction

Save the transaction hash after signing and broadcasting the unsigned transaction.

### Request Body

```json theme={null}
{
  "quote_id": "01936b4a-7c8e-7890-abcd-ef1234567890",
  "tx_hash": "0xa1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890"
}
```

| Field      | Type   | Required | Description                      |
| ---------- | ------ | -------- | -------------------------------- |
| `quote_id` | string | Yes      | UUID from quote response         |
| `tx_hash`  | string | Yes      | Transaction hash from blockchain |

### Success Response

**Status Code:** `200 OK`

```json theme={null}
{
  "message": "Transaction saved successfully"
}
```

### Error Response

**Status Code:** `400 Bad Request`

```json theme={null}
{
  "error": "Transaction not saved, please make sure you have entered the correct quote_id."
}
```

### Database Behavior

* Upserts to `tx_status` table
* Links transaction to deposit via quote\_id
* Initial status: `"indexing"`
* Used by status endpoint to track swap progress

## POST /leokit/status

Get the current status of a swap transaction.

### Request Body

```json theme={null}
{
  "quote_id": "01936b4a-7c8e-7890-abcd-ef1234567890",
  "tx_id": "0xa1b2c3d4..."
}
```

| Field      | Type   | Required    | Description                                           |
| ---------- | ------ | ----------- | ----------------------------------------------------- |
| `quote_id` | string | Yes         | UUID from quote response                              |
| `tx_id`    | string | Conditional | Required if not previously saved via save-transaction |

### Response

**Status Code:** `200 OK`

```json theme={null}
{
  "protocol": "thorchain",
  "network": "BTC",
  "req_id": "F8A2B1C3D4E5",
  "hash": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890",
  "status": "completed",
  "status_url": "https://track.ninerealms.com/tx/F8A2B1C3D4E5",
  "scanner": "https://etherscan.io/tx/0xa1b2c3...",
  "native_scanner": "https://blockchain.com/btc/tx/a1b2c3...",
  "type": "swap",
  "in_amount": 100000000,
  "from_token": "BTC.BTC",
  "to_token": "ETH.USDC-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "from_address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "to_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "date": 1705324800
}
```

### Response Fields

| Field            | Type   | Description                                          |
| ---------------- | ------ | ---------------------------------------------------- |
| `protocol`       | string | Protocol used for the swap                           |
| `network`        | string | Source blockchain network                            |
| `req_id`         | string | Protocol-specific request ID                         |
| `hash`           | string | Transaction hash on source chain                     |
| `status`         | string | Current transaction status (see Status Values below) |
| `status_url`     | string | Protocol-specific tracking URL                       |
| `scanner`        | string | Block explorer URL for destination chain             |
| `native_scanner` | string | Block explorer URL for source chain                  |
| `type`           | string | Transaction type (usually "swap")                    |
| `in_amount`      | number | Input amount in base units                           |
| `from_token`     | string | Source asset identifier                              |
| `to_token`       | string | Destination asset identifier                         |
| `from_address`   | string | Source wallet address                                |
| `to_address`     | string | Destination wallet address                           |
| `date`           | number | Unix timestamp of transaction creation               |

## Status Values

| Status      | Description                                                |
| ----------- | ---------------------------------------------------------- |
| `indexing`  | Transaction submitted, waiting for blockchain confirmation |
| `success`   | Transaction confirmed on source chain                      |
| `completed` | Swap fully executed, output received                       |
| `failed`    | Transaction failed or reverted                             |

## Status Flow

The status endpoint follows this flow:

1. **Check Cache:** Queries `tx_status` table for cached status
2. **If Completed:** Returns cached data immediately
3. **If Pending:** Fetches from protocol-specific API
4. **Update Database:** Saves new status to cache

This caching mechanism ensures fast response times for completed transactions while providing real-time updates for pending swaps.

## Protocol-Specific Status URLs

Each protocol provides its own tracking interface:

* **THORChain:** `https://track.ninerealms.com/tx/{req_id}`
* **MAYAChain:** `https://track.mayachain.info/tx/{req_id}`
* **Chainflip:** `https://scan.chainflip.io/tx/{tx_hash}`
* **Relay:** `https://relay.link/status/{req_id}`
* **NEAR:** `https://1click.chaindefuser.com/status/{req_id}`

## Example Usage

### Complete Transaction Flow

1. **Get Quote:**
   ```bash theme={null}
   GET /leokit/quote?from_asset=BTC.BTC&to_asset=ETH.USDC-0xA0b86991...&amount=100000000&destination=0x742d35...
   ```

2. **Generate Deposit:**
   ```bash theme={null}
   POST /leokit/deposit
   {
     "quote_id": "01936b4a-7c8e-7890-abcd-ef1234567890",
     "selected_protocol": "thorchain"
   }
   ```

3. **Sign & Broadcast Transaction** (client-side)

4. **Save Transaction Hash:**
   ```bash theme={null}
   POST /leokit/save-transaction
   {
     "quote_id": "01936b4a-7c8e-7890-abcd-ef1234567890",
     "tx_hash": "0xa1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890"
   }
   ```

5. **Check Status (polling):**
   ```bash theme={null}
   POST /leokit/status
   {
     "quote_id": "01936b4a-7c8e-7890-abcd-ef1234567890"
   }
   ```

### Status Polling Best Practices

* **Initial Poll:** Wait 10-15 seconds after broadcast before first status check
* **Polling Interval:** Check every 15-30 seconds for pending transactions
* **Stop Condition:** Stop polling when status is `completed` or `failed`
* **Timeout:** Consider transaction failed if status remains `indexing` for > 30 minutes