swagger.json

Overview

`swagger.json` is an OpenAPI 2.0 (Swagger) specification file describing the REST API for the **Thorchain Unchained API**. This API provides access to Thorchain blockchain data, enabling clients to retrieve account info, transaction history, transaction details, affiliate revenue, gas estimates, and broadcast raw transactions. It also supports a WebSocket endpoint for subscribing to pending and confirmed transactions.

The file defines the API endpoints (`paths`), data models (`definitions`), request/response formats, and metadata such as content types, license, and API information. This specification drives API documentation, client SDK generation, and server stubs.

API Endpoints

The API exposes a set of RESTful endpoints under `/api/v1/` and a WebSocket subscription endpoint `/`. Below is a detailed description of each endpoint:

1. WebSocket Subscription

GET /

• Tags: Websocket

• Summary: Subscribe to pending and confirmed transactions.

• Operation ID: Websocket

• Responses:

  • 200: Successful subscription (no response body described).

**Usage Example:**

Client establishes a WebSocket connection to receive real-time transaction updates.

2. Get Account Details

GET /api/v1/account/{pubkey}

• Tags: v1

• Summary: Retrieve details of an account by public key or address.

• Operation ID: GetAccount

• Parameters:

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

• Responses:

  • 200: Returns an Account object.

  • 400: Returns a BadRequestError.

  • 500: Returns an InternalServerError.

**Usage Example:**

GET /api/v1/account/abc123pubkey
Accept: application/json

3. Get Paginated Transaction History

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

• Tags: v1

• Summary: Retrieve paginated transaction history for an account.

• Operation ID: GetTxHistory

• Parameters:

  • pubkey (path, string, required): Account address or xpub.

  • cursor (query, string, optional): Pagination cursor for fetching the next page.

  • pageSize (query, integer, optional): Number of transactions per page.

• Responses:

  • 200: Returns a TxHistory object.

  • 400: Returns a BadRequestError.

  • 500: Returns an InternalServerError.

4. Get Affiliate Revenue

GET /api/v1/affiliate/revenue

• Tags: v1

• Summary: Retrieve total affiliate revenue earned over a time range.

• Operation ID: GetAffiliateRevenue

• Parameters:

  • start (query, string, optional): Start timestamp for revenue calculation.

  • end (query, string, optional): End timestamp for revenue calculation.

• Responses:

  • 200: Returns an AffiliateRevenue object.

  • 400: Returns a BadRequestError.

  • 500: Returns an InternalServerError.

5. Estimate Gas Cost

POST /api/v1/gas/estimate

• Tags: v1

• Summary: Estimate gas cost for a raw transaction.

• Operation ID: EstimateGas

• Parameters:

  • Body: JSON object with required property:

    • rawTx (string): Raw transaction data.

• Responses:

  • 200: Returns a GasAmount string.

  • 400: Returns a BadRequestError.

  • 500: Returns an InternalServerError.

**Usage Example:**

POST /api/v1/gas/estimate
Content-Type: application/json

{
  "rawTx": "ABC123RAWTRANSACTIONDATA"
}

6. Get Coinstack Info

GET /api/v1/info

• Tags: v1

• Summary: Retrieve information about the running Thorchain coinstack.

• Operation ID: GetInfo

• Responses:

  • 200: Returns an Info object.

7. Send Raw Transaction

POST /api/v1/send

• Tags: v1

• Summary: Broadcast a raw transaction to the network.

• Operation ID: SendTx

• Parameters:

  • Body: JSON object with required property:

    • rawTx (string): Raw transaction data to broadcast.

• Responses:

  • 200: Returns a TransactionHash string.

  • 400: Returns a BadRequestError.

  • 500: Returns an InternalServerError.

**Usage Example:**

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

{
  "rawTx": "ABC123RAWTRANSACTIONDATA"
}

8. Get Transaction Details

GET /api/v1/tx/{txid}

• Tags: v1

• Summary: Retrieve details of a transaction by transaction hash.

• Operation ID: GetTx

• Parameters:

  • txid (path, string, required): Transaction hash.

• Responses:

  • 200: Returns a Tx object.

  • 400: Returns a BadRequestError.

  • 500: Returns an InternalServerError.

Data Model Definitions

The `definitions` section describes all data models used in requests and responses. These models are crucial for understanding the structure and content of payloads.

Key Data Models

• Account: Extends CosmosSDKAccount, contains account balances, assets, account number, sequence, and public key.

• AffiliateRevenue: Aggregate affiliate addresses and total revenue earned in RUNE.

• Tx (Transaction): Details about a transaction, including block info, confirmations, fee, gas, messages, events, and memo.

• TxHistory: Paginated list of transactions for an account.

• GasAmount: String representing estimated gas cost.

• Info: Info about the running Thorchain coinstack, including network.

• TransactionHash: String hash representing a broadcasted transaction.

• Error Models: BadRequestError, InternalServerError, ValidationError, and generic ApiError provide structured error responses.

• Message: Represents a transaction message, including sender, receiver, type, and value.

• Value: Represents an asset amount and denomination.

• Validator, Delegation, Redelegation, Unbonding, Reward: Models related to staking and validator information, with respective nested models.

Model Composition

• Many models use inheritance via allOf to extend base types. For example, Account extends CosmosSDKAccount which extends BaseAccount.

• Complex nested structures exist to represent blockchain-specific data such as staking, events, and transaction logs.

Implementation Details and Algorithms

• The API design follows RESTful principles with clear resource paths and HTTP verbs.

• Pagination is implemented using a cursor system, where base64 encoded cursors are passed between requests to fetch pages incrementally.

• The WebSocket endpoint supports real-time subscriptions for transactions, enabling clients to react instantly to blockchain events.

• Gas estimation and transaction broadcasting rely on raw transaction data being posted to the API, indicating a trust model where clients handle transaction creation and signing.

• Data models reflect Cosmos SDK and Thorchain blockchain structures, showing tight coupling with underlying blockchain state representations.

• Error handling is standardized with clear response models for client-side and server-side errors.

Interaction with Other System Components

• This API specification is part of the Thorchain Unchained coinstack module, interacting with the blockchain node and data storage layers.

• It likely integrates with:

  • Blockchain node RPC or REST endpoints to fetch chain data.

  • Transaction mempool or broadcasting services to broadcast raw transactions.

  • Data indexing services that aggregate and paginate account and transaction data.

• The API serves as a backend interface for client applications, wallets, explorers, and affiliate tracking systems.

• WebSocket subscription enables event-driven components to receive live transaction updates.

Visual Diagram

Below is a **flowchart** representing the main API endpoints and their relationships to core data models.

flowchart TD
    WS[WebSocket Subscription<br/>"/"]
    Account["Get Account Details<br/>/api/v1/account/{pubkey}"]
    TxHistory["Get Transaction History<br/>/api/v1/account/{pubkey}/txs"]
    AffiliateRev["Get Affiliate Revenue<br/>/api/v1/affiliate/revenue"]
    GasEstimate["Estimate Gas<br/>/api/v1/gas/estimate"]
    Info["Get Coinstack Info<br/>/api/v1/info"]
    SendTx["Send Raw Transaction<br/>/api/v1/send"]
    GetTx["Get Transaction Details<br/>/api/v1/tx/{txid}"]

    WS -->|Subscribes to| Tx

    Account -->|Returns| AccountModel[Account]
    TxHistory -->|Returns| TxHistoryModel[TxHistory]
    AffiliateRev -->|Returns| AffiliateRevenueModel[AffiliateRevenue]
    GasEstimate -->|Returns| GasAmountModel[GasAmount]
    Info -->|Returns| InfoModel[Info]
    SendTx -->|Returns| TxHash[TransactionHash]
    GetTx -->|Returns| TxModel[Tx]

    %% Data models cluster
    subgraph Data_Models
      AccountModel
      TxHistoryModel
      AffiliateRevenueModel
      GasAmountModel
      InfoModel
      TxHash
      TxModel
    end

Summary

• swagger.json defines the Thorchain Unchained API specification.

• Supports querying blockchain data: accounts, transactions, affiliate revenue, and coin stack info.

• Enables broadcasting raw transactions and estimating gas costs.

• Includes a WebSocket endpoint for real-time transaction updates.

• Defines comprehensive data models reflecting blockchain and Cosmos SDK structures.

• Facilitates integration with wallets, explorers, analytics, and affiliate systems.

• Serves as a contract for client-server interaction, enabling automated tooling and SDK generation.

This file is central to exposing Thorchain blockchain data and transaction capabilities in a standardized, machine-readable format.