Transaction Management

POST /leokit/save-transaction

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

Request Body

{
  "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

{
  "message": "Transaction saved successfully"
}

Error Response

Status Code: 400 Bad Request

{
  "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

{
  "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

{
  "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:

Check Cache: Queries tx_status table for cached status
If Completed: Returns cached data immediately
If Pending: Fetches from protocol-specific API
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

Get Quote:

GET /leokit/quote?from_asset=BTC.BTC&to_asset=ETH.USDC-0xA0b86991...&amount=100000000&destination=0x742d35...

Generate Deposit:

POST /leokit/deposit
{
  "quote_id": "01936b4a-7c8e-7890-abcd-ef1234567890",
  "selected_protocol": "thorchain"
}

Sign & Broadcast Transaction (client-side)

Save Transaction Hash:

POST /leokit/save-transaction
{
  "quote_id": "01936b4a-7c8e-7890-abcd-ef1234567890",
  "tx_hash": "0xa1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890"
}

Check Status (polling):

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

Core Endpoints

Endpoint Details

Explorer API

POST /leokit/save-transaction

Request Body

Success Response

Error Response

Database Behavior

POST /leokit/status

Request Body

Response

Response Fields

Status Values

Status Flow

Protocol-Specific Status URLs

Example Usage

Complete Transaction Flow

Status Polling Best Practices

​POST /leokit/save-transaction

​Request Body

​Success Response

​Error Response

​Database Behavior

​POST /leokit/status

​Request Body

​Response

​Response Fields

​Status Values

​Status Flow

​Protocol-Specific Status URLs

​Example Usage

​Complete Transaction Flow

​Status Polling Best Practices

POST /leokit/save-transaction

Request Body

Success Response

Error Response

Database Behavior

POST /leokit/status

Request Body

Response

Response Fields

Status Values

Status Flow

Protocol-Specific Status URLs

Example Usage

Complete Transaction Flow

Status Polling Best Practices