swagger.json

Overview

[swagger.json](/projects/291/68851) is an OpenAPI 2.0 (Swagger) specification file that describes the REST API for the **Thorchain-V1 Unchained API**. This API provides programmatic access to Thorchain V1 blockchain data, allowing clients to retrieve information about accounts, transactions, and the running blockchain node.

The specification defines:

• API metadata (title, description, license).

• Supported content types (application/json).

• Available endpoints (paths), HTTP methods, parameters, and responses.

• Data models (definitions) used throughout the API, including complex types related to blockchain transactions, accounts, validators, staking, and errors.

This file acts as a contract that both API providers and consumers can rely on for consistent interaction, documentation generation, client SDK generation, and automated testing.

API Endpoints

The API exposes the following main endpoints:

1. Get Paginated Transaction History

• Path: /api/v1/account/{pubkey}/txs

• Method: GET

• Description: Retrieves a paginated list of transaction history for a specified account public key or extended public key (xpub).

• Parameters:

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

  • cursor (string, query, optional): Pagination cursor from the previous response to fetch the next page or empty for the first page.

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

• Responses:

  • 200 OK: Returns TxHistory object containing transactions and pagination metadata.

  • 400 Bad Request: Returns BadRequestError.

  • 500 Internal Server Error: Returns InternalServerError.

**Usage example:**

GET /api/v1/account/cosmos1abcxyz/txs?pageSize=10&cursor=eyJjdXJzb3IiOiIxMjMifQ==

2. Get Info About the Running Coinstack

• Path: /api/v1/info

• Method: GET

• Description: Retrieves information about the running Thorchain V1 blockchain node.

• Parameters: None

• Responses:

  • 200 OK: Returns Info object containing network information.

**Usage example:**

GET /api/v1/info

3. Get Transaction Details

• Path: /api/v1/tx/{txid}

• Method: GET

• Description: Retrieves detailed information about a specific transaction by its transaction hash.

• Parameters:

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

• Responses:

  • 200 OK: Returns Tx object with detailed transaction data.

  • 400 Bad Request: Returns BadRequestError.

  • 500 Internal Server Error: Returns InternalServerError.

**Usage example:**

GET /api/v1/tx/ABC123DEF456...

Data Models and Definitions

The `definitions` section contains detailed JSON schema definitions for the data objects used in requests and responses.

Key data models include:

1. Base Models

• BaseAccount: Basic account details such as balance, unconfirmed balance, and public key.

• BaseTx: Basic transaction details including transaction ID, block height, timestamp, and optional block hash.

• BaseTxHistory: Pagination metadata combined with a list of transactions for an account.

2. Cosmos SDK Related Models

• CosmosSDKAccount: Extends BaseAccount with account number, sequence, and asset balances.

• CosmosSDKInfo: Extends BaseInfo with blockchain network information.

• Staking: Contains current staking state including delegations, redelegations, unbondings, and rewards.

• Validator, ValidatorCommission, ValidatorUnbonding: Detailed information about validators, their commission rates, and unbonding states.

3. Transaction Models

• Tx: Complete transaction details including confirmations, gas usage, fee, memo, messages, and events.

• Message: Represents individual transaction messages with origin, source/destination addresses, type, and value.

• Event, Attribute, EventsByMsgIndex: Structured details about blockchain transaction events and their attributes.

4. Pagination and Error Models

• Pagination: Metadata for paginated responses, including the cursor string.

• BadRequestError, InternalServerError, ValidationError: Standardized error responses for client and server errors.

• ApiError: Generic error message wrapper.

5. Value Models

• Value: Represents an asset value with amount and denomination.

• ValueByAttribute: Maps attribute keys to their string values.

**Example: Tx Object Schema**

{
  "txid": "string",
  "blockHeight": 1000000,
  "timestamp": 1643052655037,
  "confirmations": 12,
  "fee": {
    "amount": "1000",
    "denom": "rune"
  },
  "gasUsed": "888",
  "gasWanted": "999",
  "index": 1,
  "memo": "test memo",
  "messages": [
    {
      "index": "0",
      "origin": "cosmos",
      "from": "cosmos1...",
      "to": "cosmos1...",
      "type": "/cosmos.bank.v1beta1.MsgSend",
      "value": {
        "amount": "123456789",
        "denom": "rune"
      }
    }
  ],
  "events": {
    "0": {
      "message": {
        "action": "transfer"
      }
    }
  },
  "value": "123456789"
}

Implementation Details and Algorithms

• Pagination: The API uses cursor-based pagination for transaction history and validator lists. The cursor is a Base64 encoded string that clients include in subsequent requests to fetch the next page.

• Error Handling: Standard HTTP status codes (400, 422, 500) are used with structured error responses to indicate client or server errors clearly.

• Data Referencing: Definitions use $ref to reuse common schemas, encouraging consistency and reducing duplication.

• Blockchain Specifics: The data models reflect blockchain-specific concepts such as staking, validators, delegations, redelegations, and unbondings, tailored for the Thorchain V1 ecosystem and Cosmos SDK compatibility.

Interaction with Other System Components

• This Swagger file documents the API layer of the Thorchain-V1 Unchained coinstack module.

• It interfaces with the blockchain node and data services to provide read access to chain state and transaction data.

• Client applications (web, mobile, services) consume this API to display wallet balances, transaction histories, validator info, and staking data.

• Other backend modules or microservices may use the API for synchronization, analytics, or integration with external systems.

• The data models correspond closely to Go structs in the codebase (indicated by x-go-name and x-go-package), facilitating code generation and strong typing in the implementation.

Visual Diagram: API Structure Flowchart

flowchart TD
    A[API Root] --> B[GET /api/v1/account/{pubkey}/txs]
    A --> C[GET /api/v1/info]
    A --> D[GET /api/v1/tx/{txid}]

    B --> B1[Parameters: pubkey (path), cursor (query), pageSize (query)]
    B --> B2[Response: TxHistory | BadRequestError | InternalServerError]

    C --> C1[No parameters]
    C --> C2[Response: Info]

    D --> D1[Parameter: txid (path)]
    D --> D2[Response: Tx | BadRequestError | InternalServerError]

    subgraph Data Models
        TxHistory
        Info
        Tx
        BadRequestError
        InternalServerError
    end

Summary

The [swagger.json](/projects/291/68851) file is a comprehensive OpenAPI specification for the Thorchain-V1 Unchained API, detailing endpoints, parameters, responses, and data schemas. It enables clients to interact with Thorchain blockchain data efficiently and reliably, supports pagination for large data sets, and provides clear error messaging. The specification also serves as a foundation for generating client SDKs, API documentation, and automated tests, promoting maintainability and consistency throughout the project lifecycle.