openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "minotari",
    "description": "",
    "license": {
      "name": ""
    },
    "version": "0.1.0"
  },
  "paths": {
    "/accounts/{name}/address": {
      "get": {
        "tags": [
          "accounts"
        ],
        "summary": "Retrieves the Tari address for a specified account.",
        "description": "Returns the account's Tari address in Base58 format along with the emoji ID\nrepresentation. This address can be shared with others to receive payments.\n\n# Path Parameters\n\n- `name`: The unique account name to query\n\n# Response\n\nReturns an [`AddressResponse`] object containing:\n- The address in Base58 encoding\n- The emoji ID representation\n\n# Errors\n\n- [`ApiError::AccountNotFound`]: The specified account does not exist\n- [`ApiError::DbError`]: Database connection or query failure\n\n# Example Response\n\n```json\n{\n  \"address\": \"f4FxMqKAPDMqAjh6hTpCnLKfEu3MmS7NRu2YmKZPvZHc2K\",\n  \"emoji_id\": \"🎉🌟🚀...\"\n}\n```",
        "operationId": "api_get_address",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "description": "Name of the account to retrieve address for",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Account address retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AddressResponse"
                }
              }
            }
          },
          "404": {
            "description": "Account not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/accounts/{name}/address_with_payment_id": {
      "post": {
        "tags": [
          "accounts"
        ],
        "summary": "Creates a Tari address with an embedded payment ID for a specified account.",
        "description": "Generates a new address that includes a payment ID, which can be used to\nidentify specific transactions or invoices. When someone sends funds to\nthis address, the payment ID will be included in the transaction.\n\n# Path Parameters\n\n- `name`: The unique account name\n\n# Request Body\n\nSee [`CreatePaymentIdAddressRequest`] for the complete request schema.\n\n# Response\n\nReturns an [`AddressWithPaymentIdResponse`] object containing:\n- The address with embedded payment ID in Base58 encoding\n- The emoji ID representation\n- The original payment ID\n\n# Errors\n\n- [`ApiError::AccountNotFound`]: The specified account does not exist\n- [`ApiError::DbError`]: Database connection or query failure\n- [`ApiError::InternalServerError`]: Failed to generate the address\n\n# Example Request\n\n```bash\ncurl -X POST http://localhost:8080/accounts/default/address_with_payment_id \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"payment_id\": \"696e766f6963652d3132333435\"}'\n```\n\n# Example Response\n\n```json\n{\n  \"address\": \"f4FxMqKAPDMqAjh6hTpCnLKfEu3MmS7NRu2YmKZPvZHc2K\",\n  \"emoji_id\": \"🎉🌟🚀...\",\n  \"payment_id_hex\": \"696e766f6963652d3132333435\"\n}\n```",
        "operationId": "api_create_address_with_payment_id",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "description": "Name of the account to create address for",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePaymentIdAddressRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Address with payment ID created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AddressWithPaymentIdResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "Account not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/accounts/{name}/balance": {
      "get": {
        "tags": [
          "accounts"
        ],
        "summary": "Retrieves the current balance for a specified account.",
        "description": "Returns the account's available balance, pending incoming transactions,\nand locked funds. This endpoint is useful for displaying wallet status\nor checking available funds before initiating a transaction.\n\n# Path Parameters\n\n- `name`: The unique account name to query\n\n# Response\n\nReturns an [`AccountBalance`] object containing:\n- Available (spendable) balance\n- Pending incoming balance\n- Locked balance (reserved for pending transactions)\n\n# Errors\n\n- [`ApiError::AccountNotFound`]: The specified account does not exist\n- [`ApiError::DbError`]: Database connection or query failure\n\n# Example Response\n\n```json\n{\n  \"available\": 10000000,\n  \"pending_incoming\": 500000,\n  \"locked\": 200000\n}\n```",
        "operationId": "api_get_balance",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "description": "Name of the account to retrieve balance for",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Account balance retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountBalance"
                }
              }
            }
          },
          "404": {
            "description": "Account not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/accounts/{name}/completed_transactions": {
      "get": {
        "tags": [
          "accounts"
        ],
        "summary": "Retrieves completed transactions for a specified account with pagination.",
        "description": "Returns a paginated list of completed transactions for the account, including\ntheir status, mined block information, and confirmation details. Transactions\nare ordered by creation time (most recent first).\n\n# Path Parameters\n\n- `name`: The unique account name to query\n\n# Query Parameters\n\n- `limit`: Maximum number of transactions to return (default: 50, max: 1000)\n- `offset`: Number of transactions to skip for pagination (default: 0)\n\n# Response\n\nReturns a list of [`CompletedTransactionResponse`] objects, each containing:\n- Transaction ID and status\n- Kernel excess (hex encoded)\n- Mining and confirmation details\n- Creation and update timestamps\n\n# Errors\n\n- [`ApiError::AccountNotFound`]: The specified account does not exist\n- [`ApiError::DbError`]: Database connection or query failure\n\n# Example Request\n\n```bash\n# Get first 50 completed transactions (default)\ncurl -X GET http://localhost:8080/accounts/default/completed_transactions\n\n# Get 100 transactions starting from offset 50\ncurl -X GET \"http://localhost:8080/accounts/default/completed_transactions?limit=100&offset=50\"\n```\n\n# Example Response\n\n```json\n[\n  {\n    \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"pending_tx_id\": \"661e8400-e29b-41d4-a716-446655440001\",\n    \"account_id\": 1,\n    \"status\": \"mined_confirmed\",\n    \"last_rejected_reason\": null,\n    \"kernel_excess_hex\": \"abc123...\",\n    \"sent_payref\": \"payref-123\",\n    \"sent_output_hash\": \"def456...\",\n    \"mined_height\": 12345,\n    \"mined_block_hash_hex\": \"789abc...\",\n    \"confirmation_height\": 12350,\n    \"broadcast_attempts\": 1,\n    \"created_at\": \"2024-01-15T10:30:00Z\",\n    \"updated_at\": \"2024-01-15T10:35:00Z\"\n  }\n]\n```",
        "operationId": "api_get_completed_transactions",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "description": "Name of the account to retrieve completed transactions for",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of transactions to return (default: 50, max: 1000)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of transactions to skip for pagination (default: 0)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Completed transactions retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/CompletedTransactionResponse"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Account not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/accounts/{name}/completed_transactions/by_payref/{payref}": {
      "get": {
        "tags": [
          "accounts"
        ],
        "summary": "Retrieves a completed transaction by its payment reference.",
        "description": "Returns a completed transaction that matches the specified payment reference.\nThe payment reference is typically assigned when a transaction is confirmed\non the blockchain.\n\n# Path Parameters\n\n- `name`: The unique account name to query\n- `payref`: The payment reference to search for\n\n# Response\n\nReturns a [`CompletedTransactionResponse`] object if found, containing:\n- Transaction ID and status\n- Kernel excess (hex encoded)\n- Mining and confirmation details\n- Creation and update timestamps\n\n# Errors\n\n- [`ApiError::AccountNotFound`]: The specified account does not exist\n- [`ApiError::NotFound`]: No transaction found with the given payment reference\n- [`ApiError::DbError`]: Database connection or query failure\n\n# Example Request\n\n```bash\ncurl -X GET http://localhost:8080/accounts/default/completed_transactions/by_payref/my-payment-ref-123\n```",
        "operationId": "api_get_completed_transaction_by_payref",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "description": "Name of the account to retrieve transaction from",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "payref",
            "in": "path",
            "description": "Payment reference to search for",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Completed transaction retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompletedTransactionResponse"
                }
              }
            }
          },
          "404": {
            "description": "Account or transaction not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/accounts/{name}/create_unsigned_transaction": {
      "post": {
        "tags": [
          "accounts"
        ],
        "summary": "Creates an unsigned one-sided transaction for external signing.",
        "description": "This endpoint constructs a complete transaction ready for signing, including\ninput selection, output creation, and fee calculation. The transaction is\nreturned in an unsigned state, allowing it to be signed by an external\nkey management system or hardware wallet.\n\n# Path Parameters\n\n- `name`: The account name to send funds from\n\n# Request Body\n\nSee [`CreateTransactionRequest`] for the complete request schema.\n\n# Response\n\nReturns a JSON object containing the unsigned transaction data, including:\n- Transaction inputs (selected UTXOs)\n- Transaction outputs (recipient outputs and change)\n- Fee information\n- Data required for signing\n\n# Errors\n\n- [`ApiError::AccountNotFound`]: The specified account does not exist\n- [`ApiError::FailedToLockFunds`]: Insufficient funds or UTXO selection failure\n- [`ApiError::FailedCreateUnsignedTx`]: Transaction construction failure\n- [`ApiError::DbError`]: Database connection or query failure\n\n# Example\n\n```bash\ncurl -X POST http://localhost:8080/accounts/default/create_unsigned_transaction \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"recipients\": [\n      {\"address\": \"f4FxMqKAPDMqAjh6hTpC...\", \"amount\": 1000000}\n    ]\n  }'\n```\n\n# Workflow\n\n1. Client calls this endpoint to create an unsigned transaction\n2. Server locks required UTXOs and constructs the transaction\n3. Client signs the transaction externally\n4. Client broadcasts the signed transaction to the network\n\n# Notes\n\n- This creates a one-sided transaction (no recipient interaction required)\n- UTXOs are automatically locked for the configured duration\n- Fee is calculated at 5 MicroMinotari per gram\n- Change outputs are created automatically when necessary",
        "operationId": "api_create_unsigned_transaction",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "description": "Name of the account to create transaction for",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTransactionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Unsigned transaction created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Value"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "Account not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/accounts/{name}/displayed_transactions": {
      "get": {
        "tags": [
          "accounts"
        ],
        "summary": "Retrieves displayed transactions for a specified account with pagination.",
        "description": "Returns a paginated list of user-friendly transactions for the account,\nincluding incoming and outgoing transactions with their status, amounts,\nand blockchain information. Transactions are ordered by block height\n(most recent first).\n\n# Path Parameters\n\n- `name`: The unique account name to query\n\n# Query Parameters\n\n- `limit`: Maximum number of transactions to return (default: 50, max: 1000)\n- `offset`: Number of transactions to skip for pagination (default: 0)\n\n# Response\n\nReturns a list of [`DisplayedTransaction`] objects, each containing:\n- Transaction ID, direction (incoming/outgoing), and source\n- Status (pending, unconfirmed, confirmed, cancelled, etc.)\n- Amount and formatted display amount\n- Counterparty information (if available)\n- Blockchain details (block height, timestamp, confirmations)\n- Fee information (for outgoing transactions)\n- Detailed input/output information\n\n# Errors\n\n- [`ApiError::AccountNotFound`]: The specified account does not exist\n- [`ApiError::DbError`]: Database connection or query failure\n\n# Example Request\n\n```bash\n# Get first 50 displayed transactions (default)\ncurl -X GET http://localhost:8080/accounts/default/displayed_transactions\n\n# Get 100 transactions starting from offset 50\ncurl -X GET \"http://localhost:8080/accounts/default/displayed_transactions?limit=100&offset=50\"\n```\n\n# Example Response\n\n```json\n[\n  {\n    \"id\": \"tx-123\",\n    \"direction\": \"incoming\",\n    \"source\": \"transfer\",\n    \"status\": \"confirmed\",\n    \"amount\": 1000000,\n    \"amount_display\": \"1.000000 XTM\",\n    \"message\": null,\n    \"counterparty\": {\n      \"address\": \"f4FxMqKAPDMqAjh6hTpC...\",\n      \"address_emoji\": \"🎉🌟...\",\n      \"label\": null\n    },\n    \"blockchain\": {\n      \"block_height\": 12345,\n      \"timestamp\": \"2024-01-15T10:30:00\",\n      \"confirmations\": 10\n    },\n    \"fee\": null,\n    \"details\": {\n      \"account_id\": 1,\n      \"total_credit\": 1000000,\n      \"total_debit\": 0,\n      \"inputs\": [],\n      \"outputs\": [...]\n    }\n  }\n]\n```",
        "operationId": "api_get_displayed_transactions",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "description": "Name of the account to retrieve displayed transactions for",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of transactions to return (default: 50, max: 1000)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of transactions to skip for pagination (default: 0)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Displayed transactions retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DisplayedTransaction"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Account not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/accounts/{name}/displayed_transactions/by_payref/{payref}": {
      "get": {
        "tags": [
          "accounts"
        ],
        "summary": "Retrieves displayed transactions by payment reference.",
        "description": "Returns displayed transactions that contain the specified payment reference.\nThis searches within the payment references stored in each transaction.\n\n# Path Parameters\n\n- `name`: The unique account name to query\n- `payref`: The payment reference to search for\n\n# Response\n\nReturns a list of [`DisplayedTransaction`] objects that contain the payment reference.\n\n# Errors\n\n- [`ApiError::AccountNotFound`]: The specified account does not exist\n- [`ApiError::DbError`]: Database connection or query failure\n\n# Example Request\n\n```bash\ncurl -X GET http://localhost:8080/accounts/default/displayed_transactions/by_payref/my-payment-ref-123\n```",
        "operationId": "api_get_displayed_transactions_by_payref",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "description": "Name of the account to retrieve transactions from",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "payref",
            "in": "path",
            "description": "Payment reference to search for",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Displayed transactions retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DisplayedTransaction"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Account not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/accounts/{name}/estimate_fees": {
      "post": {
        "tags": [
          "accounts"
        ],
        "summary": "Estimates transaction fees based on current network conditions.",
        "description": "Calculates fee estimates for Slow, Medium, and Fast priority levels by analyzing\nthe mempool state and selecting appropriate UTXOs for the requested amount.\n\n# Path Parameters\n\n- `name`: The account name to estimate fees for\n\n# Request Body\n\nSee [`EstimateFeeRequest`] for the complete request schema.\n\n# Response\n\nReturns a list of [`FeeEstimateResponse`] objects for different priorities.\n\n# Errors\n\n- [`ApiError::AccountNotFound`]: The specified account does not exist\n- [`ApiError::InternalServerError`]: Failed to query base node or calculate fees\n- [`ApiError::DbError`]: Database connection or query failure\n\n# Example Request\n\n```bash\ncurl -X POST http://localhost:8080/accounts/default/estimate_fees \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"amount\": 1000000}'\n```",
        "operationId": "api_estimate_fees",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "description": "Name of the account to estimate fees for",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EstimateFeeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Fees estimated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/FeeEstimateResponse"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "Account not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/accounts/{name}/events": {
      "get": {
        "tags": [
          "accounts"
        ],
        "summary": "Retrieves wallet events for a specified account with pagination.",
        "description": "Returns a paginated list of events that have occurred for the account, including\noutput detection, confirmation, transaction broadcasts, and blockchain\nreorganizations. Events are ordered by creation time (most recent first).\n\n# Path Parameters\n\n- `name`: The unique account name to query\n\n# Query Parameters\n\n- `limit`: Maximum number of events to return (default: 50, max: 1000)\n- `offset`: Number of events to skip for pagination (default: 0)\n\n# Response\n\nReturns a list of [`DbWalletEvent`] objects, each containing:\n- Event ID and type\n- Human-readable description\n- JSON data with event-specific details\n- Creation timestamp\n\n# Errors\n\n- [`ApiError::AccountNotFound`]: The specified account does not exist\n- [`ApiError::DbError`]: Database connection or query failure\n\n# Example Request\n\n```bash\n# Get first 50 events (default)\ncurl -X GET http://localhost:8080/accounts/default/events\n\n# Get 100 events starting from offset 50\ncurl -X GET \"http://localhost:8080/accounts/default/events?limit=100&offset=50\"\n```\n\n# Example Response\n\n```json\n[\n  {\n    \"id\": 42,\n    \"account_id\": 1,\n    \"event_type\": \"OutputDetected\",\n    \"description\": \"Detected output at height 12345\",\n    \"data_json\": \"{\\\"hash\\\":\\\"abc...\\\",\\\"block_height\\\":12345}\",\n    \"created_at\": \"2024-01-15T10:30:00\"\n  }\n]\n```",
        "operationId": "api_get_events",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "description": "Name of the account to retrieve events for",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of events to return (default: 50, max: 1000)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of events to skip for pagination (default: 0)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Account events retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DbWalletEvent"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Account not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/accounts/{name}/lock_funds": {
      "post": {
        "tags": [
          "accounts"
        ],
        "summary": "Locks funds from an account for transaction preparation.",
        "description": "This endpoint reserves UTXOs totaling at least the requested amount,\npreventing them from being used in other transactions. This is typically\nthe first step in creating a transaction, ensuring funds are available\nand reserved before constructing the transaction.\n\n# Path Parameters\n\n- `name`: The account name to lock funds from\n\n# Request Body\n\nSee [`LockFundsRequest`] for the complete request schema.\n\n# Response\n\nReturns a [`LockFundsResult`] containing:\n- The selected UTXOs to use as inputs\n- Whether a change output is required\n- Total value of locked UTXOs\n- Fee estimates with and without change\n\n# Errors\n\n- [`ApiError::AccountNotFound`]: The specified account does not exist\n- [`ApiError::FailedToLockFunds`]: Insufficient funds or UTXO selection failure\n- [`ApiError::DbError`]: Database connection or query failure\n\n# Example\n\n```bash\ncurl -X POST http://localhost:8080/accounts/default/lock_funds \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"amount\": 1000000, \"num_outputs\": 1}'\n```\n\n# Notes\n\n- Locked UTXOs are automatically released after the configured timeout\n- Use the `idempotency_key` to safely retry failed requests\n- The actual locked amount may exceed the requested amount due to UTXO granularity",
        "operationId": "api_lock_funds",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "description": "Name of the account to lock funds from",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LockFundsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Funds locked successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LockFundsResult"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "Account not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/accounts/{name}/scan_status": {
      "get": {
        "tags": [
          "accounts"
        ],
        "summary": "Retrieves the scan status for a specified account.",
        "description": "Returns information about the last scanned block, including the block height,\nblock hash, and the timestamp when the scan occurred. This is useful for\nmonitoring the wallet's synchronization progress with the blockchain.\n\n# Path Parameters\n\n- `name`: The unique account name to query\n\n# Response\n\nReturns a [`ScanStatusResponse`] object containing:\n- Last scanned block height\n- Last scanned block hash (hex encoded)\n- Timestamp when the block was scanned\n\n# Errors\n\n- [`ApiError::AccountNotFound`]: The specified account does not exist\n- [`ApiError::NotFound`]: No blocks have been scanned yet for this account\n- [`ApiError::DbError`]: Database connection or query failure\n\n# Example Response\n\n```json\n{\n  \"last_scanned_height\": 12345,\n  \"last_scanned_block_hash\": \"abc123def456...\",\n  \"scanned_at\": \"2024-01-15 10:30:00\"\n}\n```",
        "operationId": "api_get_scan_status",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "description": "Name of the account to retrieve scan status for",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Scan status retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScanStatusResponse"
                }
              }
            }
          },
          "404": {
            "description": "Account not found or no blocks scanned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/version": {
      "get": {
        "tags": [
          "accounts"
        ],
        "summary": "Retrieves the wallet version information.",
        "description": "Returns the version and name of the wallet software. This endpoint does not\nrequire authentication and can be used for health checks or compatibility\nverification.\n\n# Response\n\nReturns a [`VersionResponse`] object containing:\n- The semantic version string\n- The package name\n\n# Example Response\n\n```json\n{\n  \"version\": \"0.1.0\",\n  \"name\": \"minotari\"\n}\n```",
        "operationId": "api_get_version",
        "responses": {
          "200": {
            "description": "Version information retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AccountBalance": {
        "type": "object",
        "required": [
          "total",
          "available",
          "locked",
          "unconfirmed"
        ],
        "properties": {
          "available": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer"
              }
            }
          },
          "locked": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer"
              }
            }
          },
          "max_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "The timestamp of the most recent transaction.\n\nThe string is in ISO 8601 format. Will be `None` if the\naccount has no transactions."
          },
          "max_height": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "The maximum blockchain height among all transactions for this account.\n\nWill be `None` if the account has no transactions."
          },
          "total": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer"
              }
            }
          },
          "total_credits": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer"
              }
            }
          },
          "total_debits": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer"
              }
            }
          },
          "unconfirmed": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer"
              }
            }
          }
        }
      },
      "AddressResponse": {
        "type": "object",
        "description": "API response type for an account address.\n\nContains the Tari address in Base58 format along with the emoji ID representation.\n\n# JSON Example\n\n```json\n{\n  \"address\": \"f4FxMqKAPDMqAjh6hTpCnLKfEu3MmS7NRu2YmKZPvZHc2K\",\n  \"emoji_id\": \"🎉🌟🚀...\"\n}\n```",
        "required": [
          "address",
          "emoji_id"
        ],
        "properties": {
          "address": {
            "type": "string",
            "description": "The Tari address in Base58 encoding"
          },
          "emoji_id": {
            "type": "string",
            "description": "The emoji representation of the address"
          }
        }
      },
      "AddressWithPaymentIdResponse": {
        "type": "object",
        "description": "API response type for an address with payment ID.\n\nContains the Tari address with embedded payment ID in Base58 format,\nalong with the emoji ID representation and the original payment ID in hex.\n\n# JSON Example\n\n```json\n{\n  \"address\": \"f4FxMqKAPDMqAjh6hTpCnLKfEu3MmS7NRu2YmKZPvZHc2K\",\n  \"emoji_id\": \"🎉🌟🚀...\",\n  \"payment_id_hex\": \"696e766f6963652d3132333435\"\n}\n```",
        "required": [
          "address",
          "emoji_id",
          "payment_id_hex"
        ],
        "properties": {
          "address": {
            "type": "string",
            "description": "The Tari address with embedded payment ID in Base58 encoding"
          },
          "emoji_id": {
            "type": "string",
            "description": "The emoji representation of the address"
          },
          "payment_id_hex": {
            "type": "string",
            "description": "The payment ID that was embedded in the address (hex encoded)"
          }
        }
      },
      "ApiError": {
        "oneOf": [
          {
            "type": "object",
            "description": "A general internal server error with a descriptive message.\n\nUsed for unexpected errors that don't fit other categories.\nReturns HTTP 500 Internal Server Error.",
            "required": [
              "InternalServerError"
            ],
            "properties": {
              "InternalServerError": {
                "type": "string",
                "description": "A general internal server error with a descriptive message.\n\nUsed for unexpected errors that don't fit other categories.\nReturns HTTP 500 Internal Server Error."
              }
            }
          },
          {
            "type": "object",
            "description": "A database operation failed.\n\nThis includes connection failures, query errors, and constraint\nviolations. Returns HTTP 500 Internal Server Error.\n\n# Example Causes\n\n- Database connection pool exhausted\n- SQL query syntax error\n- Foreign key constraint violation",
            "required": [
              "DbError"
            ],
            "properties": {
              "DbError": {
                "type": "string",
                "description": "A database operation failed.\n\nThis includes connection failures, query errors, and constraint\nviolations. Returns HTTP 500 Internal Server Error.\n\n# Example Causes\n\n- Database connection pool exhausted\n- SQL query syntax error\n- Foreign key constraint violation"
              }
            }
          },
          {
            "type": "object",
            "description": "The requested account was not found.\n\nThe contained string is the account name that was not found.\nReturns HTTP 404 Not Found.\n\n# Example\n\n```json\n{\n  \"error\": \"Account 'nonexistent' not found\"\n}\n```",
            "required": [
              "AccountNotFound"
            ],
            "properties": {
              "AccountNotFound": {
                "type": "string",
                "description": "The requested account was not found.\n\nThe contained string is the account name that was not found.\nReturns HTTP 404 Not Found.\n\n# Example\n\n```json\n{\n  \"error\": \"Account 'nonexistent' not found\"\n}\n```"
              }
            }
          },
          {
            "type": "object",
            "description": "A requested resource was not found.\n\nUsed for generic not found errors beyond just accounts.\nReturns HTTP 404 Not Found.\n\n# Example\n\n```json\n{\n  \"error\": \"No blocks have been scanned yet\"\n}\n```",
            "required": [
              "NotFound"
            ],
            "properties": {
              "NotFound": {
                "type": "string",
                "description": "A requested resource was not found.\n\nUsed for generic not found errors beyond just accounts.\nReturns HTTP 404 Not Found.\n\n# Example\n\n```json\n{\n  \"error\": \"No blocks have been scanned yet\"\n}\n```"
              }
            }
          },
          {
            "type": "object",
            "description": "A bad request error for invalid input.\n\nUsed when the client sends invalid data in the request.\nReturns HTTP 400 Bad Request.\n\n# Example\n\n```json\n{\n  \"error\": \"Invalid hex in payment_id_hex: Invalid character\"\n}\n```",
            "required": [
              "BadRequest"
            ],
            "properties": {
              "BadRequest": {
                "type": "string",
                "description": "A bad request error for invalid input.\n\nUsed when the client sends invalid data in the request.\nReturns HTTP 400 Bad Request.\n\n# Example\n\n```json\n{\n  \"error\": \"Invalid hex in payment_id_hex: Invalid character\"\n}\n```"
              }
            }
          },
          {
            "type": "object",
            "description": "Failed to lock funds for a transaction.\n\nThis typically occurs when there are insufficient available funds\nor when UTXO selection fails. Returns HTTP 500 Internal Server Error.\n\n# Common Causes\n\n- Insufficient balance in the account\n- All UTXOs are already locked by other pending transactions\n- UTXO selection algorithm could not find suitable inputs",
            "required": [
              "FailedToLockFunds"
            ],
            "properties": {
              "FailedToLockFunds": {
                "type": "string",
                "description": "Failed to lock funds for a transaction.\n\nThis typically occurs when there are insufficient available funds\nor when UTXO selection fails. Returns HTTP 500 Internal Server Error.\n\n# Common Causes\n\n- Insufficient balance in the account\n- All UTXOs are already locked by other pending transactions\n- UTXO selection algorithm could not find suitable inputs"
              }
            }
          },
          {
            "type": "object",
            "description": "Failed to create an unsigned transaction.\n\nThis occurs during transaction construction after funds have been\nlocked. Returns HTTP 500 Internal Server Error.\n\n# Common Causes\n\n- Invalid recipient address format\n- Transaction size exceeds limits\n- Cryptographic operation failure",
            "required": [
              "FailedCreateUnsignedTx"
            ],
            "properties": {
              "FailedCreateUnsignedTx": {
                "type": "string",
                "description": "Failed to create an unsigned transaction.\n\nThis occurs during transaction construction after funds have been\nlocked. Returns HTTP 500 Internal Server Error.\n\n# Common Causes\n\n- Invalid recipient address format\n- Transaction size exceeds limits\n- Cryptographic operation failure"
              }
            }
          }
        ],
        "description": "Represents all possible errors returned by the REST API.\n\nEach variant corresponds to a specific error condition that can occur\nduring API request processing. The error type automatically converts\nto an appropriate HTTP response with a JSON error body.\n\n# Error Handling Pattern\n\nAPI handlers typically use the `?` operator with this error type:\n\n```rust,ignore\npub async fn handler() -> Result<Json<Data>, ApiError> {\n    let data = fetch_data().await?; // Errors automatically convert to ApiError\n    Ok(Json(data))\n}\n```\n\n# Serialization\n\nWhen serialized to JSON for API responses, errors produce:\n\n```json\n{\n  \"error\": \"Error message here\"\n}\n```"
      },
      "BlockchainInfo": {
        "type": "object",
        "required": [
          "block_height",
          "timestamp",
          "confirmations",
          "block_hash"
        ],
        "properties": {
          "block_hash": {
            "$ref": "#/components/schemas/FixedHash"
          },
          "block_height": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "confirmations": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "timestamp": {
            "type": "string"
          }
        }
      },
      "CompletedTransactionResponse": {
        "type": "object",
        "description": "API response type for a completed transaction.\n\nThis structure represents a completed transaction in the API response.\nIt contains all the relevant transaction details for display and tracking.\n\n# JSON Example\n\n```json\n{\n  \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"pending_tx_id\": \"661e8400-e29b-41d4-a716-446655440001\",\n  \"account_id\": 1,\n  \"status\": \"broadcast\",\n  \"last_rejected_reason\": null,\n  \"kernel_excess_hex\": \"abc123...\",\n  \"sent_payref\": null,\n  \"sent_output_hash\": \"def456...\",\n  \"mined_height\": null,\n  \"mined_block_hash_hex\": null,\n  \"confirmation_height\": null,\n  \"broadcast_attempts\": 1,\n  \"created_at\": \"2024-01-15T10:30:00Z\",\n  \"updated_at\": \"2024-01-15T10:31:00Z\"\n}\n```",
        "required": [
          "id",
          "pending_tx_id",
          "account_id",
          "status",
          "kernel_excess_hex",
          "broadcast_attempts",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "account_id": {
            "type": "integer",
            "format": "int64",
            "description": "Account this transaction belongs to"
          },
          "broadcast_attempts": {
            "type": "integer",
            "format": "int32",
            "description": "Number of broadcast attempts made"
          },
          "confirmation_height": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Block height where the transaction was confirmed (if confirmed)"
          },
          "created_at": {
            "type": "string",
            "description": "Timestamp when the transaction was created"
          },
          "id": {
            "type": "object",
            "properties": {
              "Tx_id": {
                "type": "integer"
              }
            }
          },
          "kernel_excess_hex": {
            "type": "string",
            "description": "Kernel excess in hexadecimal encoding"
          },
          "last_rejected_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Reason for rejection if the transaction was rejected"
          },
          "mined_block_hash_hex": {
            "type": [
              "string",
              "null"
            ],
            "description": "Block hash where the transaction was mined (hex encoded, if mined)"
          },
          "mined_height": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Block height where the transaction was mined (if mined)"
          },
          "pending_tx_id": {
            "type": "string",
            "description": "Reference to the original pending transaction"
          },
          "sent_output_hash": {
            "type": [
              "string",
              "null"
            ],
            "description": "Output hash for the sent transaction"
          },
          "sent_payref": {
            "type": [
              "string",
              "null"
            ],
            "description": "Payment reference if the transaction has been confirmed"
          },
          "status": {
            "type": "string",
            "description": "Current status of the transaction (completed, broadcast, mined_unconfirmed, mined_confirmed, rejected, canceled)"
          },
          "updated_at": {
            "type": "string",
            "description": "Timestamp when the transaction was last updated"
          }
        }
      },
      "CounterpartyInfo": {
        "type": "object",
        "required": [
          "address"
        ],
        "properties": {
          "address": {
            "type": "string"
          },
          "address_emoji": {
            "type": [
              "string",
              "null"
            ]
          },
          "label": {
            "type": [
              "string",
              "null"
            ],
            "description": "User-defined alias from address book."
          }
        }
      },
      "CreatePaymentIdAddressRequest": {
        "type": "object",
        "description": "Request body for creating an address with a payment ID.\n\n# JSON Example\n\n```json\n{\n  \"payment_id_hex\": \"696e766f6963652d3132333435\"\n}\n```",
        "required": [
          "payment_id_hex"
        ],
        "properties": {
          "payment_id_hex": {
            "type": "string",
            "description": "The payment ID to embed in the address, hex encoded.\n\nThis should be a hex-encoded byte string (e.g., \"696e766f6963652d3132333435\" for \"invoice-12345\").\nMaximum length is 256 bytes when decoded."
          }
        }
      },
      "CreateTransactionRequest": {
        "type": "object",
        "description": "Request body for creating an unsigned transaction.\n\nCreates a one-sided transaction that can be signed externally. This is\nuseful for cold wallet setups or multi-signature workflows where the\nsigning key is not available on the server.\n\n# JSON Example\n\n```json\n{\n  \"recipients\": [\n    {\n      \"address\": \"f4FxMqKAPDMqAjh6hTpC...\",\n      \"amount\": 500000,\n      \"payment_id\": \"order-123\"\n    },\n    {\n      \"address\": \"f5GxNrLBPEMrBki7iTqD...\",\n      \"amount\": 300000\n    }\n  ],\n  \"seconds_to_lock_utxos\": 7200,\n  \"idempotency_key\": \"tx-request-abc123\"\n}\n```\n\n# Notes\n\n- The total amount sent equals the sum of all recipient amounts\n- Transaction fees are calculated automatically based on transaction size\n- UTXOs are locked during transaction creation to prevent double-spending",
        "required": [
          "recipients"
        ],
        "properties": {
          "confirmation_window": {
            "type": "integer",
            "description": "Number of confirmations required"
          },
          "idempotency_key": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional idempotency key to prevent duplicate transactions.\n\nIf the same key is used in multiple requests, subsequent requests will\nreturn the original transaction rather than creating a new one."
          },
          "recipients": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RecipientRequest"
            },
            "description": "List of recipients for the transaction.\n\nAt least one recipient must be specified. Each recipient includes an\naddress and amount, with an optional payment ID."
          },
          "seconds_to_lock_utxos": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Duration in seconds to keep the input UTXOs locked.\n\nDefaults to 86,400 seconds (24 hours). The lock prevents the same UTXOs\nfrom being used in multiple transactions while the unsigned transaction\nis being signed and broadcast.",
            "default": "86400",
            "minimum": 0
          }
        }
      },
      "DbWalletEvent": {
        "type": "object",
        "description": "A database row representation of a wallet event.\n\nThis struct is used for deserializing wallet events from the database\nand serializing them for API responses.",
        "required": [
          "id",
          "account_id",
          "event_type",
          "description",
          "created_at"
        ],
        "properties": {
          "account_id": {
            "type": "integer",
            "format": "int64",
            "description": "Account this event belongs to"
          },
          "created_at": {
            "type": "string",
            "description": "Timestamp when the event was created"
          },
          "data_json": {
            "type": [
              "string",
              "null"
            ],
            "description": "JSON data containing event-specific details"
          },
          "description": {
            "type": "string",
            "description": "Human-readable description of the event"
          },
          "event_type": {
            "type": "string",
            "description": "The type of event (e.g., \"OutputDetected\", \"TransactionConfirmed\")"
          },
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Unique identifier for this event"
          }
        }
      },
      "DisplayedTransaction": {
        "type": "object",
        "description": "User-friendly transaction representation.",
        "required": [
          "id",
          "direction",
          "source",
          "status",
          "amount",
          "blockchain",
          "details"
        ],
        "properties": {
          "amount": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer"
              }
            }
          },
          "blockchain": {
            "$ref": "#/components/schemas/BlockchainInfo"
          },
          "counterparty": {
            "type": "object",
            "properties": {
              "TariAddress": {
                "type": "string"
              }
            }
          },
          "details": {
            "$ref": "#/components/schemas/TransactionDetails"
          },
          "direction": {
            "$ref": "#/components/schemas/TransactionDirection"
          },
          "fee": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/FeeInfo",
                "description": "Fee information (only populated for outgoing transactions)."
              }
            ]
          },
          "id": {
            "type": "object",
            "properties": {
              "Tx_id": {
                "type": "integer"
              }
            }
          },
          "message": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "$ref": "#/components/schemas/TransactionSource"
          },
          "status": {
            "$ref": "#/components/schemas/TransactionDisplayStatus"
          }
        }
      },
      "EstimateFeeRequest": {
        "type": "object",
        "description": "\nCalculates estimated fees for a transaction based on current mempool conditions\nand available UTXOs.\n\n# JSON Example\n\n```json\n{\n  \"amount\": 1000000,\n  \"num_outputs\": 2,\n  \"estimated_output_size\": 500\n}\n```",
        "required": [
          "amount"
        ],
        "properties": {
          "amount": {
            "type": "integer",
            "format": "int64",
            "description": "The amount to send in MicroMinotari.",
            "minimum": 0
          },
          "confirmation_window": {
            "type": "integer",
            "description": "Number of confirmations required"
          },
          "estimated_output_size": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Estimated size of each output in bytes.",
            "minimum": 0
          },
          "num_outputs": {
            "type": "integer",
            "description": "Number of outputs in the transaction (default: 1).",
            "default": "1",
            "minimum": 0
          }
        }
      },
      "FeeEstimateResponse": {
        "type": "object",
        "description": "API response type for fee estimation.\n\nContains the estimated fee details for a specific priority level.\n\n# JSON Example\n\n```json\n{\n  \"priority\": \"Medium\",\n  \"fee_per_gram\": 5,\n  \"estimated_fee\": 500,\n  \"total_amount_required\": 1000500,\n  \"input_count\": 2\n}\n```",
        "required": [
          "priority",
          "fee_per_gram",
          "estimated_fee",
          "total_amount_required",
          "input_count"
        ],
        "properties": {
          "estimated_fee": {
            "type": "integer",
            "format": "int64",
            "description": "The total estimated fee in MicroMinotari",
            "minimum": 0
          },
          "fee_per_gram": {
            "type": "integer",
            "format": "int64",
            "description": "The fee per gram used for calculation",
            "minimum": 0
          },
          "input_count": {
            "type": "integer",
            "description": "The number of input UTXOs selected",
            "minimum": 0
          },
          "priority": {
            "$ref": "#/components/schemas/FeePriorityResponse",
            "description": "The priority level for this estimate"
          },
          "total_amount_required": {
            "type": "integer",
            "format": "int64",
            "description": "The total amount required (sent amount + fee) in MicroMinotari",
            "minimum": 0
          }
        }
      },
      "FeeInfo": {
        "type": "object",
        "required": [
          "amount"
        ],
        "properties": {
          "amount": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer"
              }
            }
          }
        }
      },
      "FeePriorityResponse": {
        "type": "string",
        "description": "Priority level for fee estimation.",
        "enum": [
          "Slow",
          "Medium",
          "Fast"
        ]
      },
      "FixedHash": {
        "type": "array",
        "items": {
          "type": "integer",
          "format": "int32",
          "minimum": 0
        }
      },
      "LockFundsRequest": {
        "type": "object",
        "description": "Request body for locking funds in preparation for a transaction.\n\nThis request reserves (locks) a specified amount of funds from the account's\navailable UTXOs. Locked funds cannot be used in other transactions until\neither the lock expires or the transaction is completed/cancelled.\n\n# JSON Example\n\n```json\n{\n  \"amount\": 1000000,\n  \"num_outputs\": 2,\n  \"fee_per_gram\": 5,\n  \"estimated_output_size\": 1024,\n  \"seconds_to_lock_utxos\": 3600,\n  \"idempotency_key\": \"unique-request-id-12345\"\n}\n```\n\n# Minimal Request\n\nOnly `amount` is required; all other fields have sensible defaults:\n\n```json\n{\n  \"amount\": 1000000\n}\n```",
        "required": [
          "amount"
        ],
        "properties": {
          "amount": {
            "type": "integer",
            "format": "int64",
            "description": "The total amount to lock in MicroMinotari (1 Minotari = 1,000,000 MicroMinotari).\n\nThis should cover the intended transaction amount plus any expected fees.",
            "minimum": 0
          },
          "confirmation_window": {
            "type": "integer",
            "description": "Number of confirmations required"
          },
          "estimated_output_size": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Estimated size of each output in bytes.\n\nUsed for fee calculation. If not provided, a default estimate is used\nbased on standard output sizes.",
            "minimum": 0
          },
          "fee_per_gram": {
            "type": "integer",
            "format": "int64",
            "description": "Fee per gram for the transaction in MicroMinotari.\n\nDefaults to 5 MicroMinotari. Higher fees may result in faster confirmation\nduring periods of high network congestion.",
            "default": "5",
            "minimum": 0
          },
          "idempotency_key": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional idempotency key to prevent duplicate requests.\n\nIf provided, subsequent requests with the same key will return the\ncached result from the original request rather than locking additional\nfunds."
          },
          "num_outputs": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Number of outputs to create in the transaction.\n\nDefaults to 1. Increase this when sending to multiple recipients or when\nthe transaction requires multiple output UTXOs.",
            "default": "1",
            "minimum": 0
          },
          "seconds_to_lock_utxos": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Duration in seconds to keep the UTXOs locked.\n\nDefaults to 86,400 seconds (24 hours). After this period, locked UTXOs\nare automatically released if the transaction was not completed.",
            "default": "86400",
            "minimum": 0
          }
        }
      },
      "LockFundsResult": {
        "type": "object",
        "description": "Result of a successful fund locking operation.\n\nThis structure is returned by the `/accounts/{name}/lock_funds` endpoint\nand contains all the information needed to construct a transaction using\nthe locked UTXOs.\n\n# JSON Example\n\n```json\n{\n  \"utxos\": [...],\n  \"requires_change_output\": true,\n  \"total_value\": 1500000,\n  \"fee_without_change\": 250,\n  \"fee_with_change\": 500\n}\n```\n\n# Usage\n\nThe locked UTXOs should be used as inputs for the transaction. If\n`requires_change_output` is `true`, a change output must be created\nto return excess funds. The appropriate fee (`fee_with_change` or\n`fee_without_change`) should be used based on whether a change output\nis included.",
        "required": [
          "utxos",
          "requires_change_output",
          "total_value",
          "fee_without_change",
          "fee_with_change"
        ],
        "properties": {
          "fee_with_change": {
            "type": "integer",
            "format": "int64",
            "description": "The transaction fee if a change output is included.\n\nThis fee is higher than `fee_without_change` because the change\noutput adds to the transaction size. Use this fee when\n`requires_change_output` is `true`.",
            "minimum": 0
          },
          "fee_without_change": {
            "type": "integer",
            "format": "int64",
            "description": "The transaction fee if no change output is created.\n\nUse this fee when `requires_change_output` is `false`, or when\nintentionally burning the excess as a donation to miners.",
            "minimum": 0
          },
          "requires_change_output": {
            "type": "boolean",
            "description": "Indicates whether a change output is required.\n\nIf `true`, the total value of locked UTXOs exceeds the requested\namount plus fees, and a change output should be created to return\nthe excess to the wallet."
          },
          "total_value": {
            "type": "integer",
            "format": "int64",
            "description": "The total value of all locked UTXOs in MicroMinotari.\n\nThis is the sum of the values of all UTXOs in the `utxos` field.\nIt will be greater than or equal to the requested amount plus the\napplicable fee.",
            "minimum": 0
          },
          "utxos": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "The UTXOs that have been locked for this transaction.\n\nThese outputs are reserved and cannot be used by other transactions\nuntil the lock expires or is released. Each UTXO contains the\ncryptographic data needed to spend it."
          }
        }
      },
      "OutputStatus": {
        "type": "string",
        "enum": [
          "Unspent",
          "Locked",
          "Spent"
        ]
      },
      "RecipientRequest": {
        "type": "object",
        "description": "Represents a single recipient in a transaction request.\n\nEach recipient specifies a destination address and the amount to send.\nAn optional payment ID can be included for tracking or identification\npurposes.\n\n# JSON Example\n\n```json\n{\n  \"address\": \"f4FxMqKAPDMqAjh6hTpC...\",\n  \"amount\": 500000,\n  \"payment_id\": \"invoice-2024-001\"\n}\n```",
        "required": [
          "address",
          "amount"
        ],
        "properties": {
          "address": {
            "$ref": "#/components/schemas/TariAddressBase58",
            "description": "The recipient's Tari address in Base58 encoding.\n\nMust be a valid Tari address for the current network (mainnet, testnet, etc.)."
          },
          "amount": {
            "type": "integer",
            "format": "int64",
            "description": "The amount to send to this recipient in MicroMinotari.",
            "minimum": 0
          },
          "payment_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional payment identifier for transaction tracking.\n\nThis can be used to associate the payment with an invoice, order, or\nother business reference. The payment ID is included in the transaction\nmetadata."
          }
        }
      },
      "ScanStatusResponse": {
        "type": "object",
        "description": "API response type for the scan status endpoint.\n\nContains information about the last scanned block including height,\nblock hash, and the timestamp when it was scanned.\n\n# JSON Example\n\n```json\n{\n  \"last_scanned_height\": 12345,\n  \"last_scanned_block_hash\": \"abc123def456...\",\n  \"scanned_at\": \"2024-01-15 10:30:00\"\n}\n```",
        "required": [
          "last_scanned_height",
          "last_scanned_block_hash",
          "scanned_at"
        ],
        "properties": {
          "last_scanned_block_hash": {
            "type": "string",
            "description": "The hash of the last scanned block (hex encoded)"
          },
          "last_scanned_height": {
            "type": "integer",
            "format": "int64",
            "description": "The height of the last scanned block",
            "minimum": 0
          },
          "scanned_at": {
            "type": "string",
            "description": "Timestamp when this block was scanned"
          }
        }
      },
      "TariAddressBase58": {
        "type": "string",
        "description": "A wrapper type for [`TariAddress`] with Base58 serialization.\n\nThis type provides JSON serialization and deserialization of Tari addresses\nusing Base58 encoding, which is the standard human-readable format for\nTari addresses.\n\n# Serialization\n\nWhen serialized to JSON, the address is represented as a Base58-encoded string:\n\n```json\n\"f4FxMqKAPDMqAjh6hTpCnLKfEu3MmS7NRu2YmKZPvZHc2K\"\n```\n\n# Deserialization\n\nWhen deserializing from JSON, the string is parsed as a Base58-encoded\nTari address. Invalid addresses will result in a deserialization error.\n\n# Example\n\n```rust,ignore\nuse crate::api::types::TariAddressBase58;\n\n#[derive(Deserialize)]\nstruct Request {\n    recipient: TariAddressBase58,\n}\n\n// JSON: {\"recipient\": \"f4FxMqKAPDMqAjh6hTpC...\"}\n```"
      },
      "TransactionDetails": {
        "type": "object",
        "description": "Advanced transaction details.",
        "required": [
          "account_id",
          "total_credit",
          "total_debit",
          "inputs",
          "outputs",
          "sent_output_hashes",
          "sent_payrefs"
        ],
        "properties": {
          "account_id": {
            "type": "integer",
            "format": "int64"
          },
          "coinbase_extra": {
            "type": "object",
            "properties": {
              "Coinbase extra": {
                "type": "string"
              }
            }
          },
          "inputs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TransactionInput"
            }
          },
          "memo_hex": {
            "type": [
              "string",
              "null"
            ]
          },
          "output_type": {
            "type": "object",
            "properties": {
              "Output type": {
                "type": "string"
              }
            }
          },
          "outputs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TransactionOutput"
            }
          },
          "sent_output_hashes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FixedHash"
            },
            "description": "Hashes of outputs sent in this transaction (hex encoded).\nUsed to match pending broadcasted transactions with scanned ones."
          },
          "sent_payrefs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FixedHash"
            }
          },
          "total_credit": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer"
              }
            }
          },
          "total_debit": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer"
              }
            }
          }
        }
      },
      "TransactionDirection": {
        "type": "string",
        "enum": [
          "incoming",
          "outgoing"
        ]
      },
      "TransactionDisplayStatus": {
        "type": "string",
        "enum": [
          "pending",
          "unconfirmed",
          "confirmed",
          "cancelled",
          "reorganized",
          "rejected"
        ]
      },
      "TransactionInput": {
        "type": "object",
        "description": "A transaction input (spent UTXO).",
        "required": [
          "output_hash",
          "amount",
          "matched_output_id",
          "mined_in_block_hash"
        ],
        "properties": {
          "amount": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer"
              }
            }
          },
          "matched_output_id": {
            "type": "integer",
            "format": "int64",
            "description": "ID of the matched output in our database (if found)."
          },
          "mined_in_block_hash": {
            "$ref": "#/components/schemas/FixedHash"
          },
          "output_hash": {
            "$ref": "#/components/schemas/FixedHash"
          }
        }
      },
      "TransactionOutput": {
        "type": "object",
        "description": "A transaction output (created UTXO).",
        "required": [
          "hash",
          "amount",
          "status",
          "mined_in_block_height",
          "mined_in_block_hash",
          "output_type",
          "is_change"
        ],
        "properties": {
          "amount": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer"
              }
            }
          },
          "hash": {
            "$ref": "#/components/schemas/FixedHash"
          },
          "is_change": {
            "type": "boolean"
          },
          "mined_in_block_hash": {
            "$ref": "#/components/schemas/FixedHash"
          },
          "mined_in_block_height": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "output_type": {
            "type": "object",
            "properties": {
              "Output type": {
                "type": "string"
              }
            }
          },
          "status": {
            "$ref": "#/components/schemas/OutputStatus"
          }
        }
      },
      "TransactionSource": {
        "type": "string",
        "enum": [
          "transfer",
          "coinbase",
          "one_sided",
          "unknown"
        ]
      },
      "Value": {},
      "VersionResponse": {
        "type": "object",
        "description": "API response type for the wallet version.\n\nContains version information about the wallet software.\n\n# JSON Example\n\n```json\n{\n  \"version\": \"0.1.0\",\n  \"name\": \"minotari\"\n}\n```",
        "required": [
          "version",
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the wallet package"
          },
          "version": {
            "type": "string",
            "description": "The semantic version of the wallet (e.g., \"0.1.0\")"
          }
        }
      },
      "WalletParams": {
        "type": "object",
        "description": "Path parameters for wallet/account identification.\n\nUsed to extract the account name from URL path segments in account-related\nendpoints.\n\n# Example\n\nFor a request to `/accounts/my_wallet/balance`, the `name` field would\ncontain `\"my_wallet\"`.",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "The unique name identifying the wallet account."
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "minotari-cli",
      "description": "Minotari CLI API"
    }
  ]
}