### Create Swap Transaction Request (Swap without Affiliate Fee)

Source: https://docs.radfi.co/affiliate-fee-integration-guide

This example illustrates how to initiate a swap transaction without any affiliate fees. The `partnerFeeBps` and `partnerFeeRecipient` parameters are simply omitted from the request body.

```JSON
{
  "type": "SWAP",
  "params": {
    "tokens": ["2584333:39", "0:0"],
    "amountIn": "1000000",
    "amountOut": "100000",
    "feeRates": [3000],
    "isExactIn": true
  }
}
```

--------------------------------

### API Authentication Request Example (POST /api/auth/authenticate)

Source: https://docs.radfi.co/dev/authentication-guide

This snippet demonstrates the expected request format from the client to the backend for initial user authentication. It requires a message, signature, address, and publicKey, all generated via BIP322 signing with the user's Bitcoin wallet.

```json
{
  "message": "string",
  "signature": "string",
  "address": "string",
  "publicKey": "string"
}
```

--------------------------------

### Create Swap Transaction Request (RUNE to BTC with Affiliate Fee)

Source: https://docs.radfi.co/affiliate-fee-integration-guide

This example demonstrates a request to create a swap transaction from RUNE to BTC, including a 1% affiliate fee. The response contains a base64 encoded PSBT that needs to be signed by the user.

```JSON
{
  "type": "SWAP",
  "params": {
    "tokens": ["2584333:39", "0:0"],
    "amountIn": "1000000",
    "amountOut": "100000",
    "feeRates": [3000],
    "isExactIn": true,
    "partnerFeeBps": 10000,
    "partnerFeeRecipient": "bc1qexample1234567890abcdefghijklmnopqrstuvwxyz"
  }
}
```

--------------------------------

### Create Swap Transaction Request (BTC to RUNE with Affiliate Fee)

Source: https://docs.radfi.co/affiliate-fee-integration-guide

This example shows a request to create a swap transaction from BTC to RUNE, with a 0.5% affiliate fee. Similar to other swap requests, the response will contain a PSBT for user signing.

```JSON
{
  "type": "SWAP",
  "params": {
    "tokens": ["0:0", "2584333:39"],
    "amountIn": "1000000",
    "amountOut": "990000",
    "feeRates": [3000],
    "isExactIn": true,
    "partnerFeeBps": 5000,
    "partnerFeeRecipient": "bc1qexample1234567890abcdefghijklmnopqrstuvwxyz"
  }
}
```

--------------------------------

### Fee Calculation Formula

Source: https://docs.radfi.co/affiliate-fee-integration-guide

Explains the formula for calculating affiliate fees and provides examples for different swap types.

```APIDOC
## Fee Calculation Formula

### Description
Calculates the affiliate fee amount based on the input amount and partner fee basis points.

### Method
N/A (Formula)

### Endpoint
N/A (Formula)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (N/A)
N/A

#### Response Example
None

### Formula
```javascript
affiliateFeeAmount = floor((amountIn × partnerFeeBps) / 1,000,000)
poolAmountIn = amountIn - affiliateFeeAmount
```

**Where:**
* `amountIn`: Original input amount (in smallest unit: sats for BTC, base units for RUNE)
* `partnerFeeBps`: Affiliate fee rate in basis points (0-1,000,000)
* `affiliateFeeAmount`: Calculated fee amount (rounded down)
* `poolAmountIn`: Amount that the pool actually receives for the swap

**Minimum Fee Requirements:**
* **RUNE → BTC**: Minimum 1 RUNE (if calculated fee < 1, transaction will fail)
* **BTC → RUNE**: Minimum 546 sats (if calculated fee < 546, it will be set to 546 sats automatically)
```

--------------------------------

### GET /api/vm-blocks/incoming

Source: https://docs.radfi.co/dev/api-endpoints/vm-block

Retrieves incoming VM blocks.

```APIDOC
## GET /api/vm-blocks/incoming

### Description
Get incoming VM blocks.

### Method
GET

### Endpoint
/api/vm-blocks/incoming

### Parameters
#### Query Parameters
*None specified in the OpenAPI definition.*

### Request Example
```json
{
  "example": "No request body for GET request."
}
```

### Response
#### Success Response (200)
- **[fields]** (object) - Description of incoming VM blocks data (details not provided in OpenAPI spec)

#### Response Example
```json
{
  "example": "[Response body structure depends on the actual data]"
}
```
```

--------------------------------

### API Authentication Response Example

Source: https://docs.radfi.co/dev/authentication-guide

This snippet shows the successful response structure after initial user authentication. It includes JWT access and refresh tokens, the trading address, and wallet object, enabling subsequent authenticated API calls.

```json
{
  "accessToken": "string",
  "refreshToken": "string",
  "tradingAddress": "string",
  "wallet": {}
}
```

--------------------------------

### Initial Authentication Error Response (400)

Source: https://docs.radfi.co/dev/authentication-guide

An example of an error response from the initial authentication API, specifically indicating a signature verification failure. It includes an error code, message, and detailed explanation.

```json
{
    "code": "4007",
    "message": "auth.signatureVerificationFailed",
    "details": "BIP322 signature verification failed"
}
```

--------------------------------

### API Token Refresh Request Example (POST /api/auth/refresh-token)

Source: https://docs.radfi.co/dev/authentication-guide

This snippet demonstrates the request format for refreshing an expired access token. It requires the current refreshToken to obtain a new accessToken.

```json
{
  "refreshToken": "string"
}
```

--------------------------------

### radFi OP_12 AMM Script Example

Source: https://docs.radfi.co/technical-architecture/radfi-op_12

Illustrates the structure of a radFi AMM transaction using OP_12. This example shows a script for swapping a Rune for BTC, encoding transaction type, asset amounts, token identifiers, and fees within the OP_12 data.

```bash
# RadFi AMM Script 
# Example: Swap Rune for BTC
OP_12 # RadFi Flag (Indicates a RadFi transaction)
OP_PUSHBYTES_23 # Mark the size of swap data
02818080b08a83b7f6d39801930a4564ac8636bf020000 # Swap data

```

--------------------------------

### Error Codes Reference

Source: https://docs.radfi.co/dev/authentication-guide

A reference guide to the error codes returned by the API, including their descriptions, associated messages, and HTTP status codes.

```APIDOC
## Error Codes Reference

This section details the various error codes that can be returned by the API, helping you to understand and handle potential issues.

### Error Table

| Code | Error Type                       | Description                                      | HTTP Status      |
| ---- | -------------------------------- | ------------------------------------------------ | ---------------- |
| 4002 | Invalid Token                    | JWT token is malformed or cannot be parsed       | 401 Unauthorized |
| 4003 | Token Expired                    | JWT token has passed its expiration time         | 401 Unauthorized |
| 4004 | Token Not Found                  | No Authorization header or Bearer token provided | 401 Unauthorized |
| 4005 | Invalid Refresh Token            | Refresh token is invalid, expired, or wrong type | 400 Bad Request  |
| 4006 | User Not Found                   | JWT is valid but user doesn't exist in database  | 401 Unauthorized |
| 4007 | Signature Verification Failed    | BIP322 signature verification process fails      | 400 Bad Request  |
| 4008 | Wallet Creation Failed           | Wallet creation fails during authentication      | 400 Bad Request  |
| 4009 | Invalid Standard Taproot Address | Address doesn't match expected taproot format    | 400 Bad Request  |

### Detailed Error Descriptions

#### 4002 - Invalid Token
* **Message**: `auth.invalidToken`
* **Details**: `Invalid or malformed JWT token`
* **When**: JWT token is malformed or cannot be parsed
* **HTTP Status**: 401 Unauthorized

#### 4003 - Token Expired
* **Message**: `auth.tokenExpired`
* **Details**: `JWT token has expired`
* **When**: JWT token has passed its expiration time
* **HTTP Status**: 401 Unauthorized

#### 4004 - Token Not Found
* **Message**: `auth.tokenNotFound`
* **Details**: `JWT token not provided in request`
* **When**: No Authorization header or Bearer token provided
* **HTTP Status**: 401 Unauthorized

#### 4005 - Invalid Refresh Token
* **Message**: `auth.invalidRefreshToken`
* **Details**: `Invalid or expired refresh token`
* **When**: Refresh token is invalid, expired, or wrong type
* **HTTP Status**: 400 Bad Request

#### 4006 - User Not Found
* **Message**: `auth.userNotFound`
* **Details**: `User not found for the provided token`
* **When**: JWT is valid but user doesn't exist in database
* **HTTP Status**: 401 Unauthorized

#### 4007 - Signature Verification Failed
* **Message**: `auth.signatureVerificationFailed`
* **Details**: `BIP322 signature verification failed`
* **When**: BIP322 signature verification process fails
* **HTTP Status**: 400 Bad Request

#### 4008 - Wallet Creation Failed
* **Message**: `auth.walletCreationFailed`
* **Details**: `Failed to create wallet during authentication`
* **When**: Wallet creation fails during authentication process
* **HTTP Status**: 400 Bad Request

#### 4009 - Invalid Standard Taproot Address
* **Message**: `auth.invalidStandardTaprootAddress`
* **Details**: `Address is not a valid standard taproot address`
* **When**: Address doesn't match the expected taproot format
* **HTTP Status**: 400 Bad Request
```

--------------------------------

### GET /api/vm-blocks/difficulty-adjustment

Source: https://docs.radfi.co/dev/api-endpoints/vm-block

Retrieves information related to difficulty adjustment for VM blocks.

```APIDOC
## GET /api/vm-blocks/difficulty-adjustment

### Description
Get difficulty adjustment information for VM blocks.

### Method
GET

### Endpoint
/api/vm-blocks/difficulty-adjustment

### Parameters
#### Query Parameters
*None specified in the OpenAPI definition.*

### Request Example
```json
{
  "example": "No request body for GET request."
}
```

### Response
#### Success Response (200)
- **[fields]** (object) - Description of difficulty adjustment data (details not provided in OpenAPI spec)

#### Response Example
```json
{
  "example": "[Response body structure depends on the actual data]"
}
```
```

--------------------------------

### GET /api/setting

Source: https://docs.radfi.co/dev/api-endpoints/setting

Retrieves the current settings configuration.

```APIDOC
## GET /api/setting

### Description
Retrieves the current settings configuration.

### Method
GET

### Endpoint
/api/setting

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **(type)** - Description

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### GET /api/vm-transactions/confirmed-fee-rate/{runeId}

Source: https://docs.radfi.co/dev/api-endpoints/vm-transactions

Retrieves the confirmed fee rate for a given rune ID.

```APIDOC
## GET /api/vm-transactions/confirmed-fee-rate/{runeId}

### Description
Retrieves the confirmed fee rate by rune ID.

### Method
GET

### Endpoint
/api/vm-transactions/confirmed-fee-rate/{runeId}

### Parameters
#### Path Parameters
- **runeId** (string) - Required - The ID of the rune.

### Response
#### Success Response (200)
*Description for success response not provided in the source.

#### Response Example
*No example provided in the source.
```

--------------------------------

### Transaction Flow - Create Transaction

Source: https://docs.radfi.co/affiliate-fee-integration-guide

Initiates a swap transaction by creating an unsigned PSBT.

```APIDOC
## POST /transactions

### Description
Creates an unsigned Partially Signed Bitcoin Transaction (PSBT) for a swap, which the user will sign later.

### Method
POST

### Endpoint
`/transactions`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
**`affiliate_address`** (string) - Required - The Bitcoin address where the affiliate fee should be sent.
**`affiliate_fee_bps`** (integer) - Required - The affiliate fee rate in basis points (e.g., 10000 for 1%).
**`amount_in`** (string) - Required - The amount of the input token to swap. Represented as a string to preserve precision.
**`from_asset`** (string) - Required - The asset ticker of the input token (e.g., "RUNE", "BTC")
**`to_asset`** (string) - Required - The asset ticker of the output token (e.g., "BTC", "RUNE")
**`router`** (string) - Optional - The specific router address to use for the swap.
**`slippage_limit`** (string) - Optional - The maximum acceptable slippage for the swap. Represented as a string to preserve precision.

### Request Example
```json
{
  "affiliate_address": "bc1qxyz...",
  "affiliate_fee_bps": 10000,
  "amount_in": "100000000",
  "from_asset": "RUNE",
  "to_asset": "BTC",
  "router": "thor1...",
  "slippage_limit": "0.005"
}
```

### Response
#### Success Response (200)
- **`unsigned_tx`** (string) - The unsigned PSBT string.
- **`memo`** (string) - A memo to include in the transaction (optional).
- **`fees`** (object) - Estimated transaction fees.
  - **`asset`** (string) - The asset ticker for the fee (e.g., "BTC").
  - **`amount`** (string) - The fee amount.

#### Response Example
```json
{
  "unsigned_tx": "0001010001...",
  "memo": "AFFILIATE_FEE:10000:bc1qxyz...",
  "fees": {
    "asset": "BTC",
    "amount": "500"
  }
}
```
```

--------------------------------

### GET /api/vm-blocks

Source: https://docs.radfi.co/dev/api-endpoints/vm-block

Retrieves a list of VM blocks with options for pagination, sorting, field selection, and population of related data.

```APIDOC
## GET /api/vm-blocks

### Description
Get VM blocks with optional parameters for pagination, sorting, field selection, and populating relations.

### Method
GET

### Endpoint
/api/vm-blocks

### Parameters
#### Query Parameters
- **page** (number) - Optional - Page number (default: 1)
- **pageSize** (number) - Optional - Number of items per page (default: 10)
- **sort** (string) - Optional - Sort field and order. Use - prefix for descending. Example: -createdAt, createdAt
- **select** (string) - Optional - Fields to select (comma separated). Use + prefix to include hidden fields. Example: name,status,+holders
- **populate** (string) - Optional - Relations to populate (comma separated). Example: wallet,token

### Request Example
```json
{
  "example": "No request body for GET request."
}
```

### Response
#### Success Response (200)
- **[fields]** (object) - Description of VM blocks data (details not provided in OpenAPI spec)

#### Response Example
```json
{
  "example": "[Response body structure depends on selected fields and populated relations]"
}
```
```

--------------------------------

### GET /api/vm-transactions/top-holders/{runeId}

Source: https://docs.radfi.co/dev/api-endpoints/vm-transactions

Retrieves the top holders for a given rune ID.

```APIDOC
## GET /api/vm-transactions/top-holders/{runeId}

### Description
Retrieves the top holders by rune ID.

### Method
GET

### Endpoint
/api/vm-transactions/top-holders/{runeId}

### Parameters
#### Path Parameters
- **runeId** (string) - Required - The ID of the rune.

### Response
#### Success Response (200)
*Description for success response not provided in the source.

#### Response Example
*No example provided in the source.
```

--------------------------------

### JSON Error Response Examples

Source: https://docs.radfi.co/affiliate-fee-integration-guide

Examples of JSON error responses for common issues like missing recipients, invalid addresses, and fee calculations. These responses include error codes, messages, and detailed error information.

```json
{
  "code": "1006",
  "message": "common.invalidRequest",
  "name": "BadRequestException",
  "error": {
    "message": "common.invalidRequest",
    "details": "partnerFeeRecipient is required when partnerFeeBps is provided",
    "method": "POST",
    "path": "/api/transactions",
    "timestamp": "2025-11-26T09:16:47.918Z"
  }
}
```

```json
{
  "code": "1006",
  "message": "common.invalidRequest",
  "name": "BadRequestException",
  "error": {
    "message": "common.invalidRequest",
    "details": "partnerFeeRecipient cannot be the same as pool address",
    "method": "POST",
    "path": "/api/transactions",
    "timestamp": "2025-11-26T09:16:47.918Z"
  }
}
```

```json
{
  "code": "1006",
  "message": "common.invalidRequest",
  "name": "BadRequestException",
  "error": {
    "message": "common.invalidRequest",
    "details": "Affiliate fee must be at least 1 Rune. Calculated fee: 0 Rune",
    "method": "POST",
    "path": "/api/transactions",
    "timestamp": "2025-11-26T09:16:47.918Z"
  }
}
```

```json
{
  "code": "1006",
  "message": "common.invalidRequest",
  "name": "BadRequestException",
  "error": {
    "message": "common.invalidRequest",
    "details": "Affiliate fee is too large. Pool amount would be 0",
    "method": "POST",
    "path": "/api/transactions",
    "timestamp": "2025-11-26T09:16:47.918Z"
  }
}
```

```json
{
  "code": "<error_code>",
  "message": "wallet.insufficientBalance",
  "name": "HttpException",
  "error": {
    "message": "wallet.insufficientBalance",
    "details": "Insufficient balance",
    "method": "POST",
    "path": "/api/transactions",
    "timestamp": "2025-11-26T09:16:47.918Z"
  }
}
```

--------------------------------

### POST /migrate/pool/utxo

Source: https://docs.radfi.co/technical-architecture/bitcoin-data-availability

Migrates a pool's initialization UTXO from an old address to a new one. This process requires the pool's current UTXO and sufficient UTXOs from an admin wallet to cover transaction fees.

```APIDOC
## POST /migrate/pool/utxo

### Description
Migrates a pool's initialization UTXO from an old address to a new one. This process requires the pool's current UTXO and sufficient UTXOs from an admin wallet to cover transaction fees. The migration includes updated radFi OP_12 outputs and a runestone OP_RETURN.

### Method
POST

### Endpoint
/migrate/pool/utxo

### Parameters
#### Request Body
- **pool_init_utxo** (string) - Required - The UTXO of the pool's initialization from the old address.
- **admin_wallet_utxos** (array) - Required - An array of UTXOs from the admin wallet to cover transaction fees.

### Request Example
```json
{
  "pool_init_utxo": "<old_pool_init_utxo_id>",
  "admin_wallet_utxos": [
    "<admin_utxo_1_id>",
    "<admin_utxo_2_id>"
  ]
}
```

### Response
#### Success Response (200)
- **new_pool_init_utxo** (string) - The UTXO of the new pool initialization for the new address.
- **radfi_op12_output** (object) - Contains the radFi OP_12 script with pool initialization migration data.
  - **flag** (integer) - The migration flag (7).
  - **fee** (integer) - The fee for the migration (0).
  - **token0_id_block** (integer) - Block number for Token0 ID (0).
  - **token0_id_tx** (integer) - Transaction ID for Token0 ID (0).
  - **token1_id_block** (integer) - Block number for Token1 ID (0).
  - **token1_id_tx** (integer) - Transaction ID for Token1 ID (0).
- **runestone_op_return** (string) - The OP_RETURN data for the runestone.
- **admin_wallet_change** (string) - The change UTXO for the admin wallet.

#### Response Example
```json
{
  "new_pool_init_utxo": "<new_pool_init_utxo_id>",
  "radfi_op12_output": {
    "flag": 7,
    "fee": 0,
    "token0_id_block": 0,
    "token0_id_tx": 0,
    "token1_id_block": 0,
    "token1_id_tx": 0
  },
  "runestone_op_return": "<op_return_data>",
  "admin_wallet_change": "<admin_change_utxo_id>"
}
```
```

--------------------------------

### Calculate Swap Output with Affiliate Fee - JavaScript

Source: https://docs.radfi.co/affiliate-fee-integration-guide

Demonstrates the calculation flow for swap outputs when an affiliate fee is involved. The affiliate fee is deducted from the initial input amount before the actual swap calculation occurs, ensuring the pool receives the net amount.

```javascript
amountIn = 100 sats
affiliateFeeAmount = floor((100 × 10,000) / 1,000,000) = 1 sat
poolAmountIn = 100 - 1 = 99 sats
amountOut = calculateSwapOutput(99 sats)
```

--------------------------------

### User Authentication (Initial)

Source: https://docs.radfi.co/dev/authentication-guide

Initiates user authentication by sending a BIP322 signed message, address, and public key to the API. The API verifies the signature, creates/finds the user's wallet, and returns JWT access and refresh tokens.

```APIDOC
## POST /api/auth/authenticate

### Description
Initiates user authentication by verifying a BIP322 signature and issuing JWT access and refresh tokens.

### Method
POST

### Endpoint
/api/auth/authenticate

### Parameters
#### Request Body
- **message** (string) - Required - The message signed by the user's wallet.
- **signature** (string) - Required - The BIP322 signature of the message.
- **address** (string) - Required - The user's Bitcoin address.
- **publicKey** (string) - Required - The user's public key.

### Request Example
```json
{
  "message": "some_signed_message",
  "signature": "sig...",
  "address": "bc1q...",
  "publicKey": "pubkey..."
}
```

### Response
#### Success Response (200)
- **accessToken** (string) - The JWT access token (valid for 10 minutes).
- **refreshToken** (string) - The JWT refresh token (valid for 7 days).
- **tradingAddress** (string) - The user's trading address.
- **wallet** (object) - Details of the user's wallet.

#### Response Example
```json
{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi...",
  "tradingAddress": "tb1q...",
  "wallet": {
    "id": "wallet_id_123",
    "address": "bc1q..."
  }
}
```
```

--------------------------------

### Frontend Implementation - Header Format

Source: https://docs.radfi.co/dev/authentication-guide

Details on the required `Authorization` header format for making authenticated requests to protected API endpoints.

```APIDOC
## Frontend Implementation - Header Format

### Header Format

All protected API calls require the `Authorization` header to be set with a Bearer token.

**Header:**
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

Replace `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` with the actual access token obtained after successful authentication.
```

--------------------------------

### POST /api/auth/authenticate

Source: https://docs.radfi.co/dev/authentication-guide

Initiates user authentication by verifying a BIP322 signature and returning JWT access and refresh tokens.

```APIDOC
## POST /api/auth/authenticate

### Description
This endpoint is used to perform the initial authentication of a user. It requires a BIP322 signature and related details to verify the user's identity. Upon successful verification, it returns JWT access and refresh tokens, along with wallet information.

### Method
POST

### Endpoint
/api/auth/authenticate

### Parameters
#### Request Body
- **message** (string) - Required - The message to be signed.
- **signature** (string) - Required - The BIP322 signature.
- **address** (string) - Required - The user's wallet address.
- **publicKey** (string) - Required - The user's public key.

### Request Example
```json
{
    "message": "1759413612750",
    "signature": "AUE5z8iM+Y3M6ey8j7zluhzf75R...XZ+nQH7lRAQ==",
    "address": "bc1py270r0u9y8248s45tpe479j8w...xspezlzu",
    "publicKey": "0324e27cae4cec8374d1c970caf...7c03"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the authentication was successful.
- **data** (object) - Contains authentication tokens and wallet details.
  - **tradingAddress** (string) - The trading address associated with the wallet.
  - **accessToken** (string) - The JWT access token.
  - **refreshToken** (string) - The JWT refresh token.
  - **wallet** (object) - Details of the authenticated wallet.
    - **_id** (string) - The unique identifier for the wallet.
    - **deletedAt** (null) - Timestamp of deletion, if applicable.
    - **tradingAddress** (string) - The trading address of the wallet.
    - **userAddress** (string) - The user's primary address.
    - **userPublicKey** (string) - The user's public key.
    - **requiredSignNumber** (integer) - The number of signatures required for transactions.
    - **pubKeysNum** (integer) - The total number of public keys associated with the wallet.
    - **agreeTerm** (boolean) - Indicates if the user agreed to terms.
    - **createdAt** (integer) - Timestamp of wallet creation.
    - **updatedAt** (integer) - Timestamp of last wallet update.
    - **__v** (integer) - Version key.
- **message** (string) - A message indicating the success of the authentication and token expiry information.

#### Response Example (Success)
```json
{
    "success": true,
    "data": {
        "tradingAddress": "bc1p...",
        "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "wallet": {
            "_id": "68e1fc5a73513ef283c17b2f",
            "deletedAt": null,
            "tradingAddress": "bc1p...",
            "userAddress": "bc1pge...",
            "userPublicKey": "4ae4...",
            "requiredSignNumber": 2,
            "pubKeysNum": 2,
            "agreeTerm": false,
            "createdAt": 1759640666632,
            "updatedAt": 1759640666632,
            "__v": 0
        }
    },
    "message": "Authentication successful. AccessToken expires in 10 minutes. RefreshToken expires in 7 days."
}
```

#### Error Response (400)
- **code** (string) - The error code.
- **message** (string) - A machine-readable error message.
- **details** (string) - A human-readable description of the error.

#### Response Example (Error)
```json
{
    "code": "4007",
    "message": "auth.signatureVerificationFailed",
    "details": "BIP322 signature verification failed"
}
```
```

--------------------------------

### Shell Script for Protected API Demo

Source: https://docs.radfi.co/dev/authentication-guide

This shell script is used to run a demonstration of protected API endpoints. It is part of the testing framework for the authentication system.

```bash
./test/auth/scripts/demo-protected-apis.sh
```

--------------------------------

### Get Mempool Fee (Radfi API)

Source: https://docs.radfi.co/dev/api-endpoints/transactions

Endpoint to retrieve the estimated mempool fee for transactions. This GET request does not require a request body and returns a 200 status code upon success.

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Radfi API",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://staging.api.radfi.co",
      "description": "Staging"
    }
  ],
  "paths": {
    "/api/transactions/mempool-fee": {
      "get": {
        "operationId": "TransactionController_getMempoolFee",
        "parameters": [],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "tags": [
          "transactions"
        ]
      }
    }
  }
}
```

--------------------------------

### Wallet Endpoints

Source: https://docs.radfi.co/dev/authentication-guide

Provides endpoints for wallet management, including creation, listing, and retrieving detailed information.

```APIDOC
## POST /api/wallets

### Description
Creates a new wallet for the user.

### Method
POST

### Endpoint
/api/wallets

## GET /api/wallets

### Description
Lists all wallets associated with the authenticated user.

### Method
GET

### Endpoint
/api/wallets

## GET /api/wallets/details/:id

### Description
Retrieves detailed information for a specific wallet identified by its ID.

### Method
GET

### Endpoint
/api/wallets/details/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the wallet.
```

--------------------------------

### Get Wallets API Endpoint

Source: https://docs.radfi.co/dev/api-endpoints/wallets

Retrieves a paginated list of wallets. Supports filtering by page number, page size, sort order, selected fields, and relations to populate. Uses GET request to the /api/wallets endpoint.

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Radfi API",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://staging.api.radfi.co",
      "description": "Staging"
    }
  ],
  "paths": {
    "/api/wallets": {
      "get": {
        "operationId": "WalletController_paginate",
        "summary": "Get wallets",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "description": "Page number (default: 1)",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "pageSize",
            "required": false,
            "in": "query",
            "description": "Number of items per page (default: 10)",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "sort",
            "required": false,
            "in": "query",
            "description": "Sort field and order. Use - prefix for descending. Example: -createdAt, createdAt",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "select",
            "required": false,
            "in": "query",
            "description": "Fields to select (comma separated). Use + prefix to include hidden fields. Example: name,status,+holders",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "populate",
            "required": false,
            "in": "query",
            "description": "Relations to populate (comma separated). Example: wallet,token",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Get wallets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BaseResponseDto"
                }
              }
            }
          }
        },
        "tags": [
          "wallets"
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "BaseResponseDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object"
          },
          "metaData": {
            "$ref": "#/components/schemas/ResponseMetaData"
          }
        },
        "required": [
          "code",
          "message",
          "data",
          "metaData"
        ]
      },
      "ResponseMetaData": {
        "type": "object",
        "properties": {
          "totalItems": {
            "type": "number"
          },
          "currentPage": {
            "type": "number"
          },
          "pageSize": {
            "type": "number"
          },
          "totalPages": {
            "type": "number"
          }
        },
        "required": [
          "totalItems",
          "currentPage",
          "pageSize",
          "totalPages"
        ]
      }
    }
  }
}

```

--------------------------------

### GET: Get Etched Rune by ID

Source: https://docs.radfi.co/dev/api-endpoints/etch

Retrieves details for a specific etched rune by its ID. Optional query parameters include 'select' for specific fields, 'populate' for related data, and 'sort' for ordering. Returns a BaseResponseDto containing the rune details.

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Radfi API",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://staging.api.radfi.co",
      "description": "Staging"
    }
  ],
  "paths": {
    "/api/etch/runes/details": {
      "get": {
        "operationId": "EtchController_getEtchedRune",
        "summary": "Get etch rune by id",
        "parameters": [
          {
            "name": "select",
            "required": false,
            "in": "query",
            "description": "Fields to select (comma separated). Use + prefix to include hidden fields. Example: name,status,+holders",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "populate",
            "required": false,
            "in": "query",
            "description": "Relations to populate (comma separated). Example: wallet,token",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "required": false,
            "in": "query",
            "description": "Sort field and order. Use - prefix for descending. Example: -createdAt",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "etch rune",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BaseResponseDto"
                }
              }
            }
          }
        },
        "tags": [
          "etch"
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "BaseResponseDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object"
          },
          "metaData": {
            "$ref": "#/components/schemas/ResponseMetaData"
          }
        },
        "required": [
          "code",
          "message",
          "data",
          "metaData"
        ]
      },
      "ResponseMetaData": {
        "type": "object",
        "properties": {
          "totalItems": {
            "type": "number"
          },
          "currentPage": {
            "type": "number"
          },
          "pageSize": {
            "type": "number"
          },
          "totalPages": {
            "type": "number"
          }
        },
        "required": [
          "totalItems",
          "currentPage",
          "pageSize",
          "totalPages"
        ]
      }
    }
  }
}
```

--------------------------------

### Swap Operations

Source: https://docs.radfi.co/technical-architecture/bitcoin-data-availability

Details on how to perform swap operations within the Radfi protocol, covering both Bitcoin to Rune and Rune to Bitcoin swaps.

```APIDOC
## Swap in One Pool

### Description
This endpoint facilitates atomic swaps between different token pairs within a single liquidity pool. It handles both Bitcoin-to-Rune and Rune-to-Bitcoin swap scenarios, managing pool liquidity and user balances.

### Method
This is an on-chain transaction, not a traditional API call.

### Endpoint
N/A (On-chain transaction)

### Parameters
**Inputs:**
*   **n inputs (n <= 10):** Pool liquidity UTXOs
*   **Remaining inputs:** Trading wallet's UTXOs to facilitate the swap (containing funds for swapping and transaction fees).

**Outputs:**
*   **n outputs:** New pool liquidity UTXOs reflecting updated reserves.
*   **Output n to m:** `radFi OP_12` outputs containing the encoded swap data.
*   **Output m+1:** `Runestone OP_RETURN` output containing metadata for new liquidity and Rune outputs.
*   **Output m+2:** Trading wallet's output UTXO for the swapped token.
*   **Output m+3:** Trading wallet's change UTXO for the swapped token (if applicable).
*   **Output m+4:** Trading wallet's change UTXO for the original token (if applicable).

### Swap Bitcoin to Rune Example

**Inputs:**
*   **Inputs 0-1:** Pool liquidity UTXOs.
*   **Input 2:** Trading wallet's UTXOs containing Bitcoin funds to swap and cover the transaction fee.

**Outputs:**
*   **Outputs 0-1:** New pool liquidity UTXOs.
*   **Output 2:** `radFi OP_12` script containing swap data:
    *   **Byte 0 (Flag):** `2` (Swap flag)
    *   **Byte 1:**
        *   **First bit (IsExactIn):** `true`
        *   **Remaining 7 bits (PoolsCount, uint8):** `1`
    *   **Remaining bytes:** 8 `uvarint128` values:
        *   **AmountIn:** `1000`
        *   **AmountOut:** `7444327141368519190`
        *   **SequenceNumber:** `66`
        *   **Fee:** `100` (1%)
        *   **Input TokenId - Block:** `0`
        *   **Input TokenId - Tx:** `0`
        *   **Output TokenId - Block:** `885548`
        *   **Output TokenId - Tx:** `319`
*   **Output 3:** `Runestone OP_RETURN` containing data for the liquidity in the new UTXOs and Rune output for the trading wallet.
*   **Output 4:** Trading wallet's swap output UTXO (Rune).
*   **Output 5:** Trading wallet's Rune change UTXO.
*   **Output 6:** Trading wallet's Bitcoin change UTXO.

### Swap Runes to Bitcoin Example

**Inputs:**
*   **Inputs 0-3:** Pool liquidity UTXOs.
*   **Input 4:** Trading wallet's UTXOs containing Bitcoin funds to cover the transaction fee.
*   **Inputs 5-6:** Trading wallet's UTXOs containing Rune funds to swap.

**Outputs:**
*   **Outputs 0-3:** New pool liquidity UTXOs.
*   **Output 4:** `radFi OP_12` script containing swap data:
    *   **Byte 0 (Flag):** `2` (Swap flag)
    *   **Byte 1:**
        *   **First bit (IsExactIn):** `true`
        *   **Remaining 7 bits (PoolsCount, uint8):** `1`
    *   **Remaining bytes:** 8 `uvarint128` values:
        *   **AmountIn:** `11000000000000000000`
        *   **AmountOut:** `1299`
        *   **SequenceNumber:** `69`
        *   **Fee:** `100` (1%)
        *   **Input TokenId - Block:** `885548`
        *   **Input TokenId - Tx:** `319`
        *   **Output TokenId - Block:** `0`
        *   **Output TokenId - Tx:** `0`
*   **Output 5:** `Runestone OP_RETURN` containing data for the liquidity in the new UTXOs and Rune change for the trading wallet.
*   **Output 6:** Trading wallet's swap output UTXO (Bitcoin).
*   **Output 7:** Trading wallet's Rune change UTXO.
*   **Output 8:** Trading wallet's Bitcoin change UTXO.
```

--------------------------------

### Get Positions Endpoint (OpenAPI)

Source: https://docs.radfi.co/dev/api-endpoints/positions

This snippet defines the GET /api/positions endpoint using OpenAPI 3.0. It specifies query parameters for pagination, sorting, field selection, and relation population. The endpoint is used to retrieve position data from the Radfi API.

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Radfi API",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://staging.api.radfi.co",
      "description": "Staging"
    }
  ],
  "paths": {
    "/api/positions": {
      "get": {
        "operationId": "PositionController_paginate",
        "summary": "Get positions",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "description": "Page number (default: 1)",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "pageSize",
            "required": false,
            "in": "query",
            "description": "Number of items per page (default: 10)",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "sort",
            "required": false,
            "in": "query",
            "description": "Sort field and order. Use - prefix for descending. Example: -createdAt, createdAt",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "select",
            "required": false,
            "in": "query",
            "description": "Fields to select (comma separated). Use + prefix to include hidden fields. Example: name,status,+holders",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "populate",
            "required": false,
            "in": "query",
            "description": "Relations to populate (comma separated). Example: wallet,token",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "tags": [
          "positions"
        ]
      }
    }
  }
}
```

--------------------------------

### GET /api/vm-transactions/count-unconfirmed-requests

Source: https://docs.radfi.co/dev/api-endpoints/vm-transactions

Counts the number of unconfirmed requests for VM transactions.

```APIDOC
## GET /api/vm-transactions/count-unconfirmed-requests

### Description
Counts unconfirmed requests for VM transactions.

### Method
GET

### Endpoint
/api/vm-transactions/count-unconfirmed-requests

### Response
#### Success Response (200)
*Description for success response not provided in the source.

#### Response Example
*No example provided in the source.
```

--------------------------------

### GET /api/vm-transactions/fee-rate

Source: https://docs.radfi.co/dev/api-endpoints/vm-transactions

Retrieves the current fee rate for VM transactions.

```APIDOC
## GET /api/vm-transactions/fee-rate

### Description
Retrieves the fee rate for VM transactions.

### Method
GET

### Endpoint
/api/vm-transactions/fee-rate

### Response
#### Success Response (200)
*Description for success response not provided in the source.

#### Response Example
*No example provided in the source.
```

--------------------------------

### Define SettingUpdateDto

Source: https://docs.radfi.co/dev/api-endpoints/models

Defines the data structure for updating settings. It requires a key (enum: virtual_mint, transaction, pool) and a data object.

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Radfi API",
    "version": "1.0"
  },
  "components": {
    "schemas": {
      "SettingUpdateDto": {
        "type": "object",
        "properties": {
          "key": {"type": "string", "enum": ["virtual_mint", "transaction", "pool"]},
          "data": {"type": "object"}
        },
        "required": [
          "key",
          "data"
        ]
      }
    }
  }
}
```