Skip to main content

​
API Reference

Welcome to the OdinTrade API reference documentation. Our API enables seamless integration with the OdinTrade protocol for atomic swaps between Bitcoin and EVM chains.

​
Base URL

All API endpoints are relative to this base URL (only testnet is available at the moment): 
https://api.odinx.org/testnet

​
Available Endpoints

​
Swap Operations

​
Get Token Swap Details

POST /swap-details Calculate an estimated exchange rates and amountOut, for token pairs. Request Body: 
{
  "amountIn": number,
  "tokenInSymbol": string,
  "tokenOutSymbol": string,
  "chainIn": "bitcoin" | "ethereum",
  "chainOut": "bitcoin" | "ethereum",
  "addressIn": string,
  "addressOut": string,
  "walletPartnerId": string (optional)
}
Response: 
{
  "amountOut": number,
  "rate": string
}

​
Get Maximum Amount Out

POST /max-amount-out Calculate maximum receivable tokens based on available balance. Request Body: 
{
  "tokenInSymbol": string,
  "tokenOutSymbol": string,
  "chainIn": "bitcoin" | "ethereum",
  "chainOut": "bitcoin" | "ethereum",
  "addressIn": string,
  "addressOut": string
}
Response: 
{
  "maxAmountOut": number,
  "maxAmountIn": number
}

​
Create Swap

POST /create-swap Initialize a new atomic swap. The user will also provide a signature, which is the timestamp signature made with addressIn to prove that they are the real owner of the address that will lock the funds in chainIn. If it is not clear why amountOut is required, instead of amountIn, please refer to the Protocol Flow section. Request Body: 
{
  "amountOut": number,
  "tokenInSymbol": string,
  "tokenOutSymbol": string,
  "chainIn": "bitcoin" | "ethereum",
  "chainOut": "bitcoin" | "ethereum",
  "addressIn": string,
  "addressOut": string,
  "timestamp": number,
  "signature": string,
  "userAddressPubkeyIn": string (optional),
  "userAddressPubkeyOut": string (optional),
  "walletPartnerId": string (optional)
}
Response: 
{
  "swapId": string,
  "userClaimToSign": string (optional)
}

​
Confirm Swap

POST /confirm-swap/{swapId} Confirm and execute the swap. The Liquidity Node will check userClaimSigned and userAddressPubkeyOut if chainOut is Bitcoin. Ethereum doesn’t require a signature for the user claim. Request Body: 
{
  "userClaimSigned": string (optional),
}
Response: 
{
  "transactionHash": string,
  "estimatedAmountIn": number,
  "estimatedRate": number,
}

​
HTLC Operations

​
Create User HTLC

POST /user-create-htlc/{swapId} Generate HTLC for user’s part of the swap. Required userAddressPubkeyIn if chainIn is Bitcoin. Request Body: 
{
  "userAddressPubkeyIn": string (optional)
}
Response: 
{
  "amountIn": number,
  "rate": number,
  "userHtlcToSign": string[]
}

​
Confirm User HTLC

POST /user-confirm-htlc/{swapId} Submit signed HTLC transaction. Required userAddressPubkeyIn if chainIn is Bitcoin. Request Body: 
{
  "userHtlcSigned": string[]
}
Response: 
{
  "transactionHash": string
}

​
Status and History

​
Get Swap Status

GET /swap/{swapId} Get detailed information about a specific swap. Response: 
{
  "id": string,
  "status": string,
  "htlc1TransactionHash": string,
  "htlc2TransactionHash": string,
  "brokerClaimedTransactionHash": string,
  "userClaimedTransactionHash": string,
  "createdAt": string,
  "tokenInSymbol": string,
  "tokenOutSymbol": string,
  "tokenInAddress": string,
  "tokenOutAddress": string,
  "chainIn": "bitcoin" | "ethereum",
  "chainOut": "bitcoin" | "ethereum",
  "amountIn": number,
  "amountOut": number,
  "rate": number
}

​
Get All Swaps History

GET /all-swaps-history Retrieve historical swap transactions. Query Parameters:
  • addressIn (optional): Filter by input address
  • addressOut (optional): Filter by output address
Response: 
[
  {
    "id": string,
    "tokenInSymbol": string,
    "tokenOutSymbol": string,
    "amountIn": number,
    "amountOut": number,
    "rate": number,
    "addressIn": string,
    "addressOut": string,
    "chainIn": string,
    "chainOut": string,
    "status": string,
    "htlc1TransactionHash": string,
    "htlc2TransactionHash": string,
    "htlc1Output": string,
    "htlc2Output": string,
    "timestampBrokerClaimConfirmation": string,
    "timestampUserClaimConfirmation": string,
    "brokerClaimedTransactionHash": string,
    "userClaimedTransactionHash": string,
    "createdAt": string,
    "updatedAt": string
  }
]

​
Error Handling

The API uses standard HTTP status codes:
  • 200: Success
  • 400: Bad Request - Invalid parameters
  • 401: Unauthorized - Invalid API key
  • 403: Forbidden - Insufficient permissions
  • 404: Not Found - Resource doesn’t exist
  • 429: Too Many Requests - Rate limit exceeded
  • 500: Internal Server Error - Please contact support

​
Rate Limiting

API requests are limited to 100 requests per minute per API key. Exceeding this limit will result in a 429 Too Many Requests response.