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

# API Reference

> Complete API reference for OdinTrade

# 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:**

```json theme={null}
{
  "amountIn": number,
  "tokenInSymbol": string,
  "tokenOutSymbol": string,
  "chainIn": "bitcoin" | "ethereum",
  "chainOut": "bitcoin" | "ethereum",
  "addressIn": string,
  "addressOut": string,
  "walletPartnerId": string (optional)
}
```

**Response:**

```json theme={null}
{
  "amountOut": number,
  "rate": string
}
```

#### Get Maximum Amount Out

`POST /max-amount-out`

Calculate maximum receivable tokens based on available balance.

**Request Body:**

```json theme={null}
{
  "tokenInSymbol": string,
  "tokenOutSymbol": string,
  "chainIn": "bitcoin" | "ethereum",
  "chainOut": "bitcoin" | "ethereum",
  "addressIn": string,
  "addressOut": string
}
```

**Response:**

```json theme={null}
{
  "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](/essentials/protocol-flow) section.

**Request Body:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "userClaimSigned": string (optional),
}
```

**Response:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "userAddressPubkeyIn": string (optional)
}
```

**Response:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "userHtlcSigned": string[]
}
```

**Response:**

```json theme={null}
{
  "transactionHash": string
}
```

### Status and History

#### Get Swap Status

`GET /swap/{swapId}`

Get detailed information about a specific swap.

**Response:**

```json theme={null}
{
  "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:**

```json theme={null}
[
  {
    "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.