swagger.json

Overview

The **swagger.json** file is an OpenAPI 3.0 specification document describing the REST API for the [@shapeshiftoss/gnosis-api](/projects/291/69075) project (version 10.0.0). This API exposes endpoints to interact with an Ethereum Virtual Machine (EVM)-compatible blockchain node, providing features such as querying account data, transaction history, transaction details, sending transactions, JSON-RPC calls, token metadata, and gas fee estimations.

It defines the API's paths, HTTP methods, request/response schemas, parameters, and error responses in a machine-readable format. This specification is useful for generating client SDKs, API documentation, and automated testing tools.

Detailed Explanation of Components

1. Schemas (Components > Schemas)

Schemas define the structure of request and response payloads used throughout the API.

BaseInfo

Description: Basic information about the running coinstack (blockchain network).
Type: Object
Properties:
- network (string) - The name of the network (e.g., "mainnet").
Required: network
Example:
```
{
  "network": "mainnet"
}
```

TokenBalance

Description: Information about a token including the balance for an address.
Type: Object
Properties:
- contract (string) - Token contract address.
- decimals (number) - Number of decimals the token uses.
- name (string) - Token name.
- symbol (string) - Token symbol.
- type (string) - Token type (e.g., ERC20).
- id (string, optional) - NFT or multi-token identifier.
- balance (string) - Token balance for the account.
Required: contract, decimals, name, symbol, type, balance

Account

Description: Details about an EVM account.
Type: Object
Properties:
- balance (string) - Confirmed balance.
- unconfirmedBalance (string) - Unconfirmed balance.
- pubkey (string) - Account public key (address).
- nonce (number) - Transaction nonce.
- tokens (array of TokenBalance) - Tokens held by the account.
Required: All above properties.

BadRequestError

Description: Error response for HTTP 400 Bad Request.
Type: Object
Properties:
- error (string) - Error message.
Required: error

ValidationError

Description: Error response for HTTP 422 Validation Error.
Type: Object
Properties:
- message (string, enum: "Validation failed") - Validation failure message.
- details (object) - Additional details about the validation errors.
Required: message, details

InternalServerError

Description: Error response for HTTP 500 Internal Server Error.
Type: Object
Properties:
- message (string) - Error message.
Required: message

TokenTransfer

Description: Info about a token transfer.
Type: Object
Properties:
- contract (string) - Token contract address.
- decimals (number) - Token decimals.
- name (string) - Token name.
- symbol (string) - Token symbol.
- type (string) - Token type.
- id (string, optional) - NFT or multi-token identifier.
- from (string) - Sender address.
- to (string) - Recipient address.
- value (string) - Amount transferred.
Required: All except id which is optional.

InternalTx

Description: Details of an internal transaction within an EVM transaction.
Type: Object
Properties:
- from (string) - Sender address.
- to (string) - Recipient address.
- value (string) - Value transferred.
Required: All properties.

Tx (Transaction)

Description: Complete details about an EVM transaction.
Type: Object
Properties:
- txid (string) - Transaction hash.
- blockHash (string) - Block hash containing the transaction.
- blockHeight (number) - Block number.
- timestamp (number) - Unix timestamp of the block.
- from (string) - Sender address.
- to (string) - Recipient address.
- confirmations (number) - Number of confirmations.
- value (string) - Value transferred.
- fee (string) - Transaction fee.
- gasLimit (string) - Gas limit set.
- gasUsed (string, optional) - Gas used (if available).
- gasPrice (string) - Gas price.
- status (number) - Status code (e.g., 1 = success).
- inputData (string, optional) - Input data (hex-encoded).
- tokenTransfers (array of TokenTransfer, optional) - Tokens transferred in this tx.
- internalTxs (array of InternalTx, optional) - Internal transactions.
Required: Most core properties except optional fields like gasUsed, inputData, tokenTransfers, internalTxs.

BaseTxHistory_Tx_ / TxHistory

Description: Paginated transaction history for an account.
Type: Object
Properties:
- cursor (string, optional) - Cursor for pagination.
- pubkey (string) - Account public key.
- txs (array of Tx) - List of transactions.
Required: pubkey, txs

SendTxBody

Description: Request body for sending a raw transaction.
Type: Object
Properties:
- hex (string) - Serialized raw transaction hex string.
Required: hex

RPCRequest

Description: JSON-RPC request object.
Type: Object
Properties:
- jsonrpc (string, enum: "2.0") - JSON-RPC version.
- id (string or number) - Request identifier.
- method (string) - RPC method name.
- params (array) - Parameters for the RPC call.
Required: jsonrpc, id, method

RPCResponse

Description: JSON-RPC response object.
Type: Object
Properties:
- jsonrpc (string, enum: "2.0") - JSON-RPC version.
- id (string or number) - Matches request ID.
- result (any) - Response result.
- error (object, optional) - Error object with message, code, and optional data.
Required: jsonrpc, id

TokenMetadata

Description: Metadata about an NFT token (ERC-721/ERC-1155).
Type: Object
Properties:
- name (string) - Token name.
- description (string) - Token description.
- media (object) - Media associated with token.
  - url (string) - Media URL.
  - type (string enum: "image", "video") - Media type.
Required: name, description, media

TokenType

Description: Enum for supported token types.
Type: String enum: "erc721", "erc1155"

GasEstimate

Description: Gas estimation result.
Type: Object
Properties:
- gasLimit (string) - Estimated gas limit.
Required: gasLimit

EstimateGasBody

Description: Request body for estimating gas of a transaction.
Type: Object
Properties:
- data (string) - Hex-encoded transaction data.
- from (string) - Sender address.
- to (string) - Recipient address.
- value (string) - Amount to send.
Required: All properties.

Fees

Description: Fee details for legacy or EIP-1559 transactions.
Type: Object
Properties:
- gasPrice (string) - Gas price.
- maxFeePerGas (string, optional) - Max fee per gas (EIP-1559).
- maxPriorityFeePerGas (string, optional) - Max priority fee per gas (EIP-1559).
Required: gasPrice

GasFees

Description: Recommended current gas fees for slow, average, and fast confirmation speeds.
Type: Object
Properties:
- baseFeePerGas (string, optional) - Current base fee per gas.
- slow (Fees) - Fees for slow confirmation.
- average (Fees) - Fees for average confirmation.
- fast (Fees) - Fees for fast confirmation.
Required: slow, average, fast

2. API Paths and Operations

Path	HTTP Method	OperationId	Description
`/api/v1/info`	GET	GetInfo	Retrieve basic info about the running coinstack.
`/api/v1/account/{pubkey}`	GET	GetAccount	Get account details by pubkey (address).
`/api/v1/account/{pubkey}/txs`	GET	GetTxHistory	Get paginated transaction history by pubkey.
`/api/v1/tx/{txid}`	GET	GetTransaction	Get detailed info about a specific transaction.
`/api/v1/send`	POST	SendTx	Broadcast a raw serialized transaction hex.
`/api/v1/jsonrpc`	POST	DoRpcRequest	Make a JSON-RPC call(s) to the node.
`/api/v1/metadata/token`	GET	GetTokenMetadata	Retrieve metadata for a specific token (NFT).
`/api/v1/gas/estimate`	POST	EstimateGas	Estimate gas cost for a transaction.
`/api/v1/gas/fees`	GET	GetGasFees	Get current recommended gas fees for transactions.

3. Important Implementation Details

Strict Schema Validation: All request and response payloads use strict JSON schema definitions with additionalProperties: false to enforce exact payload structure.
Pagination Support: The transaction history endpoint supports cursor-based pagination with optional query parameters for page size and block range filtering.
JSON-RPC Support: The API supports forwarding JSON-RPC requests to the underlying node, supporting both single and batch requests/responses.
Error Handling: Standardized error response schemas for 400, 422, and 500 HTTP status codes are defined and used consistently across endpoints.
Token Metadata: Supports ERC-721 and ERC-1155 token standards with media information (image/video types).
Gas Fees: Supports both legacy gas pricing and EIP-1559 fee model with recommended fees for different confirmation speeds.

4. Interaction with Other System Components

Blockchain Node: The API acts as a middleware between clients and an EVM-compatible blockchain node, abstracting node JSON-RPC calls and exposing higher-level REST endpoints.
Clients: External clients (web apps, wallets, services) consume this API to fetch account info, transaction history, send transactions, query token metadata, and estimate gas fees.
Token Metadata Storage: Token metadata retrieval likely interacts with off-chain storage (e.g., IPFS URLs) referenced inside the metadata schema.
Transaction Broadcast: The /send endpoint submits serialized transactions to the node for propagation to the blockchain network.
Gas Fee Oracle: The /gas/fees endpoint probably integrates with a fee estimation service or calculates fees based on recent blocks to provide recommended fees.

Usage Examples

Example: Get Account Details

**Request:**

GET /api/v1/account/0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF HTTP/1.1
Accept: application/json

**Response (200 OK):**

{
  "balance": "0",
  "unconfirmedBalance": "0",
  "nonce": 0,
  "pubkey": "0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF",
  "tokens": [
    {
      "balance": "1337",
      "contract": "0xc770EEfAd204B5180dF6a14Ee197D99d808ee52d",
      "decimals": 18,
      "name": "FOX",
      "symbol": "FOX",
      "type": "ERC20"
    }
  ]
}

Example: Send Raw Transaction

**Request:**

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

{
  "hex": "0xf86c808504a817c80082520894f6...b844a9059cbb000000000000000..."
}

**Response (200 OK):**

"0x6850c6f3af68eb60a211af8f07f5b305375d0c94786b79a48371f5143953cb26"

Example: JSON-RPC Request (eth_blockNumber)

**Request:**

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

{
  "jsonrpc": "2.0",
  "id": "test",
  "method": "eth_blockNumber",
  "params": []
}

**Response:**

{
  "jsonrpc": "2.0",
  "id": "test",
  "result": "0x1a4"
}

Visual Diagram: API Path and Schema Relationships

flowchart TD
    subgraph Paths
        Info[/GET /api/v1/info/]
        Account[/GET /api/v1/account/{pubkey}/]
        TxHistory[/GET /api/v1/account/{pubkey}/txs/]
        Transaction[/GET /api/v1/tx/{txid}/]
        SendTx[/POST /api/v1/send/]
        JsonRpc[/POST /api/v1/jsonrpc/]
        TokenMeta[/GET /api/v1/metadata/token/]
        GasEstimate[/POST /api/v1/gas/estimate/]
        GasFees[/GET /api/v1/gas/fees/]
    end

    subgraph Schemas
        BaseInfo[BaseInfo]
        AccountSchema[Account]
        TxHistorySchema[TxHistory]
        Tx[Tx]
        SendTxBody[SendTxBody]
        RPCRequest[RPCRequest]
        RPCResponse[RPCResponse]
        TokenMetadata[TokenMetadata]
        GasEstimateSchema[GasEstimate]
        GasFeesSchema[GasFees]
        ErrorSchemas[BadRequestError, ValidationError, InternalServerError]
    end

    Info -->|returns| BaseInfo
    Account -->|returns| AccountSchema
    TxHistory -->|returns| TxHistorySchema
    Transaction -->|returns| Tx
    SendTx -->|accepts| SendTxBody
    SendTx -->|returns| string
    JsonRpc -->|accepts| RPCRequest
    JsonRpc -->|returns| RPCResponse
    TokenMeta -->|returns| TokenMetadata
    GasEstimate -->|accepts| EstimateGasBody[EstimateGasBody]
    GasEstimate -->|returns| GasEstimateSchema
    GasFees -->|returns| GasFeesSchema

    AccountSchema -->|has| TokenBalance[TokenBalance]
    TxHistorySchema -->|contains| Tx
    Tx -->|contains| TokenTransfer[TokenTransfer]
    Tx -->|contains| InternalTx[InternalTx]
    RPCResponse -->|may contain| ErrorSchemas

Summary

The swagger.json file is a comprehensive OpenAPI 3.0 spec for a blockchain REST API.
It defines endpoints for querying blockchain data, sending transactions, and making JSON-RPC calls.
The API uses detailed and strict JSON schemas for request/response validation.
It supports key blockchain constructs such as accounts, transactions, token balances, and gas fee estimation.
The spec includes error handling and pagination mechanisms.
This file serves as the contract between the API implementation and its consumers, enabling interoperability and tooling support.

This documentation provides a full understanding of the API described in the [swagger.json](/projects/291/68851) file and can serve as a reference for developers implementing clients or servers based on this specification.