swagger.json

Overview

This file is an **OpenAPI 3.0 specification** document defining the REST API for the [@shapeshiftoss/litecoin-api](/projects/291/69281) project, version `10.0.0`. It describes the API endpoints, request/response schemas, and error handling related to Litecoin blockchain data and transaction management.

The API provides functionality to:

• Retrieve general coinstack information.

• Query account details and transaction history by addresses or extended public keys.

• Access unspent transaction outputs (UTXOs).

• Get detailed transaction data (both parsed and raw).

• Broadcast raw transactions to the network.

• Fetch recommended network fees.

This specification serves as the contract between the backend Litecoin node or service and API consumers, enabling programmatic access to Litecoin blockchain data and transaction operations in a standardized way.

Detailed Components and Endpoints

Components

The [components](/projects/291/69205) section defines reusable schemas (data models) used in request and response bodies, along with empty placeholders for examples, headers, parameters, request bodies, responses, and security schemes.

Schemas

• BaseInfo

  • Description: Basic info about the running coinstack.

  • Properties:

    • network (string): The network name (e.g., "mainnet", "testnet").

  • Required: network

• Address

  • Description: Info about a single address associated with an extended public key.

  • Properties:

    • balance (string): Balance of the address.

    • pubkey (string): Public key of the address.

  • Required: balance, pubkey

• Account

  • Description: Info about an address or extended public key account.

  • Properties:

    • balance (string): Confirmed balance.

    • unconfirmedBalance (string): Unconfirmed balance.

    • pubkey (string): Extended public key or address.

    • addresses (array of Address): Addresses associated with the account.

    • nextReceiveAddressIndex (number): Next unused receive address index.

    • nextChangeAddressIndex (number): Next unused change address index.

  • Required: balance, unconfirmedBalance, pubkey

• BadRequestError

  • Description: Details for HTTP 400 Bad Request.

  • Properties:

    • error (string): Error message.

  • Required: error

• ValidationError

  • Description: Details for HTTP 422 Validation Error.

  • Properties:

    • message (string, enum: "Validation failed"): General validation failure message.

    • details (object): Additional error details.

  • Required: message, details

• InternalServerError

  • Description: Details for HTTP 500 Internal Server Error.

  • Properties:

    • message (string): Error message.

  • Required: message

• Vin (Transaction Input)

  • Properties include:

    • txid (string): ID of the referenced transaction.

    • vout (string): Output index.

    • sequence (number): Sequence number.

    • coinbase (string): Coinbase data (if coinbase tx).

    • scriptSig (object): Script signature hex.

    • addresses (array of string): Addresses involved.

    • value (string): Value of input.

• Vout (Transaction Output)

  • Properties include:

    • value (string): Output value.

    • n (number): Output index.

    • opReturn (string, optional): OP_RETURN data.

    • scriptPubKey (object): Script public key in hex.

    • addresses (array of string): Addresses receiving output.

  • Required: value, n, scriptPubKey

• Tx (Transaction)

  • Properties include:

    • txid (string): Transaction ID.

    • blockHash (string): Block hash containing transaction.

    • blockHeight (number): Block height.

    • timestamp (number): Unix timestamp of transaction.

    • vin (array of Vin): Transaction inputs.

    • vout (array of Vout): Transaction outputs.

    • confirmations (number): Number of confirmations.

    • value (string): Total transaction value.

    • fee (string): Transaction fee.

    • hex (string): Raw transaction hex.

  • Required: all except blockHash (optional)

• BaseTxHistory_Tx_

  • Paginated transaction history details.

  • Properties:

    • cursor (string): Pagination cursor.

    • pubkey (string): Account pubkey.

    • txs (array of Tx): List of transactions.

  • Required: pubkey, txs

• TxHistory

  • Alias for BaseTxHistory_Tx_.

  • Description: Transaction history.

• Utxo (Unspent Transaction Output)

  • Properties:

    • txid (string): Transaction ID.

    • vout (number): Output index.

    • value (string): Output value.

    • height (number): Block height.

    • confirmations (number): Confirmations count.

    • address (string): Associated address.

    • path (string): HD wallet path.

    • locktime (number): Locktime.

    • coinbase (boolean): Coinbase flag.

  • Required: txid, vout, value, confirmations

• RawTx

  • Detailed raw transaction info as returned by the node.

  • Properties include:

    • txid, hash, version, size, vsize, weight, locktime, vin, vout, hex, blockhash, confirmations, time, blocktime.

    • vin and vout include nested script details.

  • Required: all above properties.

• SendTxBody

  • Request body for sending raw transaction.

  • Properties:

    • hex (string): Serialized raw transaction hex.

  • Required: hex

• NetworkFee

  • Info about a recommended network fee.

  • Properties:

    • satsPerKiloByte (number): Fee rate in satoshis per kilobyte.

    • blocksUntilConfirmation (number): Estimated confirmation time in blocks.

  • Required: both properties.

• NetworkFees

  • Recommended network fees categorized by speed.

  • Properties:

    • fast (NetworkFee)

    • average (NetworkFee)

    • slow (NetworkFee)

Paths (Endpoints)

All endpoints are under `/api/v1/` base path and tagged with `"v1"`.

1. GET /api/v1/info

• OperationId: GetInfo

• Description: Retrieves information about the running Litecoin coinstack.

• Response 200: Returns BaseInfo schema.

• Security: None (public endpoint).

• Usage Example:

GET /api/v1/info HTTP/1.1
Accept: application/json

Response:

{
  "network": "mainnet"
}

2. GET /api/v1/account/{pubkey}

• OperationId: GetAccount

• Description: Get detailed info about an account by address or extended public key.

• Parameters:

  • pubkey (path, string, required): Account address or extended public key.

• Responses:

  • 200: Returns Account schema.

  • 400: BadRequestError

  • 422: ValidationError

  • 500: InternalServerError

• Usage Example:

GET /api/v1/account/xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiKp9ybq4dK HTTP/1.1
Accept: application/json

Response (200):

{
  "balance": "100000000",
  "unconfirmedBalance": "0",
  "pubkey": "xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiKp9ybq4dK",
  "addresses": [
    {
      "balance": "50000000",
      "pubkey": "LTCaddress1"
    },
    {
      "balance": "50000000",
      "pubkey": "LTCaddress2"
    }
  ],
  "nextReceiveAddressIndex": 2,
  "nextChangeAddressIndex": 1
}

3. GET /api/v1/account/{pubkey}/txs

• OperationId: GetTxHistory

• Description: Fetch transaction history for an address or extended public key.

• Parameters:

  • pubkey (path, string, required)

  • cursor (query, string, optional): Encoded cursor for pagination.

  • pageSize (query, number, optional, default 10): Number of transactions per page.

• Responses:

  • 200: TxHistory schema.

  • 400, 422, 500: error schemas as above.

• Usage Example:

GET /api/v1/account/xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiKp9ybq4dK/txs?pageSize=5 HTTP/1.1
Accept: application/json

4. GET /api/v1/account/{pubkey}/utxos

• OperationId: GetUtxos

• Description: Get all unspent transaction outputs for an address or extended public key.

• Parameters:

  • pubkey (path, string, required)

• Responses:

  • 200: Array of Utxo objects.

  • 400, 422, 500: error schemas.

• Usage Example:

GET /api/v1/account/LTCTestAddress/utxos HTTP/1.1
Accept: application/json

5. GET /api/v1/tx/{txid}

• OperationId: GetTransaction

• Description: Retrieve detailed transaction information by transaction ID.

• Parameters:

  • txid (path, string, required)

• Responses:

  • 200: Tx schema.

  • 400, 422, 500: error schemas.

• Usage Example:

GET /api/v1/tx/abcd1234 HTTP/1.1
Accept: application/json

6. GET /api/v1/tx/{txid}/raw

• OperationId: GetRawTransaction

• Description: Retrieve raw transaction details directly from the Litecoin node.

• Parameters:

  • txid (path, string, required)

• Responses:

  • 200: RawTx schema.

  • 400, 422, 500: error schemas.

• Usage Example:

GET /api/v1/tx/abcd1234/raw HTTP/1.1
Accept: application/json

7. POST /api/v1/send

• OperationId: SendTx

• Description: Broadcasts a serialized raw transaction hex to the Litecoin network.

• Request Body:

  • JSON object containing hex (string) — the serialized raw transaction.

• Responses:

  • 200: Returns transaction ID as string on success.

  • 400, 422, 500: error schemas.

• Usage Example:

POST /api/v1/send HTTP/1.1
Content-Type: application/json

{
  "hex": "0200000001abcd..."
}

8. GET /api/v1/fees

• OperationId: GetNetworkFees

• Description: Retrieves recommended network fees categorized by speed.

• Responses:

  • 200: NetworkFees schema.

  • 400, 500: error schemas.

• Usage Example:

GET /api/v1/fees HTTP/1.1
Accept: application/json

Response:

{
  "fast": {
    "satsPerKiloByte": 50000,
    "blocksUntilConfirmation": 1
  },
  "average": {
    "satsPerKiloByte": 30000,
    "blocksUntilConfirmation": 3
  },
  "slow": {
    "satsPerKiloByte": 10000,
    "blocksUntilConfirmation": 6
  }
}

Implementation Details and Algorithms

• This file is a static API specification and does not contain executable code.

• It models a RESTful API that interfaces with Litecoin blockchain data and transaction services.

• The schemas reflect typical Litecoin transaction constructs such as inputs (vin), outputs (vout), UTXOs, and accounts derived from extended public keys (xpub).

• Pagination in transaction history is implemented via a cursor query parameter carrying base64 encoded state.

• Error handling is standardized using HTTP status codes and typed error response bodies.

• The API relies on the backend node or service to provide actual blockchain data, including raw transaction hex and fee estimates.

• The SendTx endpoint facilitates broadcasting transactions by accepting raw hex payloads, enabling clients to handle signing externally.

Interaction with Other System Components

• This API specification is intended to be implemented on top of a Litecoin node or a blockchain data service that maintains wallet/account info, mempool, and blockchain state.

• Clients (such as wallets, explorers, or backend services) consume this API to:

  • Display account balances and transaction histories.

  • Fetch UTXOs for constructing new transactions.

  • Retrieve detailed transaction data for verification or display.

  • Broadcast newly created transactions to the network.

  • Obtain fee estimates for transaction fee calculation.

• The API forms the interface layer that abstracts direct node RPC calls into a standardized HTTP API suitable for web and mobile clients.

• It integrates with cryptographic key management systems external to this API for signing transactions prior to broadcasting.

Visual Diagram

This file defines primarily **schemas** and **REST endpoints**, so a **flowchart** showing the main endpoints and their relationships to schemas provides the clearest overview.

flowchart TD
    Info[GET /api/v1/info] -->|response| BaseInfoSchema[BaseInfo]
    Account[GET /api/v1/account/{pubkey}] -->|response| AccountSchema[Account]
    TxHistory[GET /api/v1/account/{pubkey}/txs] -->|response| TxHistorySchema[TxHistory]
    Utxos[GET /api/v1/account/{pubkey}/utxos] -->|response| UtxoSchemaArray[Array of Utxo]
    Tx[GET /api/v1/tx/{txid}] -->|response| TxSchema[Tx]
    RawTx[GET /api/v1/tx/{txid}/raw] -->|response| RawTxSchema[RawTx]
    SendTx[POST /api/v1/send] -->|request body| SendTxBodySchema[SendTxBody]
    SendTx -->|response| TxId[String]
    Fees[GET /api/v1/fees] -->|response| NetworkFeesSchema[NetworkFees]

    subgraph Schemas
        BaseInfoSchema
        AccountSchema
        TxHistorySchema
        UtxoSchemaArray
        TxSchema
        RawTxSchema
        SendTxBodySchema
        NetworkFeesSchema
    end

Summary

The [swagger.json](/projects/291/68968) file is a comprehensive OpenAPI specification for the ShapeShift Litecoin API, defining a robust set of REST endpoints to interact with Litecoin accounts, transactions, UTXOs, and network fees. It standardizes request/response formats and error handling, serving as the formal API contract for clients and backend implementers. The spec models typical blockchain data constructs and supports pagination, raw transaction broadcasting, and fee estimation — essential for building wallets, explorers, and other blockchain-integrated applications.