swagger.json

Overview

`swagger.json` is an OpenAPI 3.0 specification file defining the RESTful API for the [@shapeshiftoss/solana-api](/projects/291/69281) project, version 10.0.0. This API provides comprehensive access to Solana blockchain data and operations, including account info, transaction history, token details, fee estimations, raw transaction broadcasting, and JSON-RPC requests to a Solana node.

The file serves as both a machine-readable contract and human-readable documentation for API consumers and developers, enabling automated client generation, testing, and validation.

Components

The file organizes API schemas, endpoints, and operations under the OpenAPI standard elements:

• Info: Metadata about the API (title, version, license).

• Servers: Specifies the base URL for API calls.

• Paths: Defines REST endpoints, HTTP methods, parameters, requests, and responses.

• Components: Contains reusable schemas (data models), security schemes (empty here), and examples.

Detailed Explanation of Schemas

The [components.schemas](/projects/291/69205) section defines the data structures used throughout the API. Below are key schemas with explanations and usage contexts.

BaseInfo

• Description: Basic info about the running coinstack.

• Properties:

  • network (string, required): Network name (e.g., "mainnet").

**Usage**: Returned by `/api/v1/info` to identify the blockchain environment.

TokenBalance

• Description: Information about a token balance for an address.

• Properties:

  • id (string): Token identifier.

  • decimals (number): Number of decimals supported.

  • name (string): Token name.

  • symbol (string): Token symbol.

  • type (string): Token type.

  • balance (string): Balance amount as a string for precision.

• All properties are required.

**Usage**: Included in [Account.tokens](/projects/291/69316) to represent tokens held by an account.

Account

• Description: Represents an address or extended public key account.

• Properties:

  • balance (string): Confirmed balance.

  • unconfirmedBalance (string): Balance pending confirmation.

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

  • tokens (array of TokenBalance): List of token balances.

• All properties are required.

**Usage**: Returned by `/api/v1/account/{pubkey}` to provide account state.

Tx (Transaction)

• Description: Contains detailed info about a blockchain transaction.

• Combines BaseTx (basic details) and EnrichedTransaction (extended info).

**BaseTx Properties**:

• txid (string): Transaction signature.

• blockHash (string, optional): Hash of the block containing the tx.

• blockHeight (number, required): Block height.

• timestamp (number, required): Unix timestamp.

**EnrichedTransaction Properties**:

• description (string): Human-readable summary.

• type (TransactionType enum): Transaction category.

• source (Source enum): Origin of the transaction.

• fee (number): Fee paid.

• feePayer (string): Account paying the fee.

• signature (string): Transaction signature.

• slot (number): Slot number.

• nativeTransfers (array of NativeTransfer): Native currency transfers.

• tokenTransfers (array of TokenTransfer): Token transfers.

• accountData (array of AccountData): Balance changes per account.

• transactionError (nullable): Error info if present.

• instructions (array of Instruction): Instructions executed.

• events (TransactionEvent): Related events (NFT, swap, compressed).

**Usage**: Returned by `/api/v1/tx/{txid}` endpoint.

TransactionType (Enum)

Enumerates a wide range of transaction types supported, including NFT bids, swaps, loans, auctions, token minting, and more, allowing clients to understand transaction semantics.

Source (Enum)

Lists various sources or programs that can initiate transactions or operations, including marketplaces (Magic Eden, OpenSea), protocols (Serum, Raydium), and system programs.

NativeTransfer

• Description: Represents native token transfer details.

• Properties:

  • fromUserAccount (string, nullable): Sender account.

  • toUserAccount (string, nullable): Recipient account.

  • amount (number): Amount transferred.

TokenTransfer

• Description: Represents a token transfer between accounts.

• Properties:

  • fromUserAccount (string, nullable)

  • toUserAccount (string, nullable)

  • fromTokenAccount (string, nullable)

  • toTokenAccount (string, nullable)

  • tokenAmount (number)

  • decimals (number)

  • tokenStandard (TokenStandard enum)

  • mint (string): Token mint address.

Instruction and InnerInstruction

• Instruction: Represents a transaction instruction including program ID, data payload, accounts, and any inner instructions.

• InnerInstruction: Nested instructions within a main instruction.

RPCRequest and RPCResponse

• Defines the JSON-RPC 2.0 request and response structures used to send arbitrary RPC calls to the Solana node.

PriorityFees

• Description: Provides recommended priority fees to include in transactions for different speed tiers (slow, average, fast).

• Properties:

  • baseFee (string)

  • slow (string)

  • average (string)

  • fast (string)

API Endpoints

The API exposes several REST endpoints under `/api/v1/` namespace:

Important Implementation Details

• Detailed Data Models: The API leverages comprehensive data models capturing nuanced blockchain states such as token balances, native and token transfers, instructions, and events.

• Transaction Enrichment: The transaction model (Tx) is enriched with human-readable descriptions, error info, and event data, facilitating easier client-side understanding.

• Extensive Enum Types: TransactionType and Source enums include a broad range of Solana-specific transaction categories and sources, supporting many use cases including NFTs, swaps, loans, and staking.

• Pagination Support: Transaction history supports cursor-based pagination via optional query parameters.

• Error Handling: Defined error schemas (BadRequestError, ValidationError, InternalServerError) standardize error responses.

• JSON-RPC Proxy: The jsonrpc endpoint allows clients to send arbitrary JSON-RPC calls to the underlying Solana node, enabling advanced or custom queries beyond REST endpoints.

Interactions with Other System Components

• Solana Node: The API acts as a middleware between clients and the Solana blockchain node, querying blockchain data and broadcasting transactions.

• Clients: Frontend applications, wallets, or services consume this API for blockchain interaction, account management, and transaction status.

• Token and NFT Marketplaces: The API supports various marketplace-specific transaction types and sources, enabling integration with NFT sales, bids, and swaps.

• Fee Estimation Module: Provides recommended transaction fees and estimates compute units required, aiding in transaction fee optimization.

• Raw Transaction Handling: Serialization and submission of raw transactions allow clients to create and send custom transactions programmatically.

Usage Examples

Get Account Information

**Request:**

GET /api/v1/account/2bUNK6eVUmXyxeSDURsWdqi1KK8BYu4egnzyi3xDYc9M
Accept: application/json

**Response:**

{
  "pubkey": "2bUNK6eVUmXyxeSDURsWdqi1KK8BYu4egnzyi3xDYc9M",
  "balance": "0",
  "unconfirmedBalance": "0",
  "tokens": []
}

Send Raw Transaction

**Request:**

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

{
  "hex": "base64-encoded-transaction-hex"
}

**Response:**

"5KDSVYdUSSKSgTcq1PJFmo3vMSNeP383Q3xVqWhGX4xExaYtYmcygA7wncwz8gVgZMbhKtg5ZekD9fsF6T5mCMAv"

Mermaid Diagram - API Structure Overview

This flowchart illustrates the core API endpoints and their relationships to main data schemas.

flowchart TD
    Info["GET /api/v1/info\n(BaseInfo)"]
    Account["GET /api/v1/account/{pubkey}\n(Account)"]
    TxHistory["GET /api/v1/account/{pubkey}/txs\n(TxHistory)"]
    Transaction["GET /api/v1/tx/{txid}\n(Tx)"]
    SendTx["POST /api/v1/send\n(SendTxBody)"]
    PriorityFees["GET /api/v1/fees/priority\n(PriorityFees)"]
    EstimateFees["POST /api/v1/fees/estimate\n(EstimateFeesBody)"]
    JsonRpc["POST /api/v1/jsonrpc\n(RPCRequest / RPCResponse)"]
    Token["GET /api/v1/token/{id}\n(Token)"]

    Info -->|returns| BaseInfo[BaseInfo]
    Account -->|returns| AccountSchema[Account]
    TxHistory -->|returns| TxHistorySchema[TxHistory]
    Transaction -->|returns| TxSchema[Tx]
    SendTx -->|returns| String[Transaction Signature]
    PriorityFees -->|returns| PriorityFeesSchema[PriorityFees]
    EstimateFees -->|returns| String[Estimated Fee]
    JsonRpc -->|returns| RpcResponse[RPCResponse or Batch]
    Token -->|returns| TokenSchema[Token]

Summary

`swagger.json` precisely defines the REST API interface for interacting with Solana blockchain data and transactions, focusing on:

• Account and token data retrieval.

• Transaction details and history.

• Sending and estimating transactions.

• JSON-RPC forwarding for advanced queries.

It provides a rich set of data models capturing Solana-specific blockchain semantics and supports extensible transaction types and sources, suitable for wallets, explorers, and DeFi/NFT applications.

This file acts as the central API contract and documentation for developers integrating with the [@shapeshiftoss/solana-api](/projects/291/69281) ecosystem.