swagger.json

Overview

[swagger.json](/projects/291/68851) is an OpenAPI 3.0 specification file defining the RESTful API contract for the [@shapeshiftoss/bnbsmartchain-api](/projects/291/68970) project, version 10.0.0. This API provides endpoints for interacting with the Binance Smart Chain (BSC) or compatible Ethereum Virtual Machine (EVM) blockchain nodes, supporting operations such as retrieving account information, transaction details, sending raw transactions, fetching token metadata, estimating gas costs, and querying current gas fees.

The file describes the API's available HTTP paths, request parameters, expected responses, and data schemas in a machine-readable JSON format. It serves as a comprehensive reference for developers integrating with the BNB Smart Chain API and can be used to generate client SDKs, server stubs, or interactive API documentation.

Components

Schemas

This section defines reusable data models (schemas) used throughout the API requests and responses. Each schema includes properties, types, descriptions, and validation rules.

• BaseInfo
  Contains basic information about the running coinstack (blockchain network instance).

  • Properties:

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

  • Usage: Returned by /api/v1/info endpoint.

• TokenBalance
  Details of a token held by an account, including balance and identification.

  • Properties:

    • contract (string, required): Token contract address.

    • decimals (number, required): Number of decimals used by the token.

    • name (string, required): Token name.

    • symbol (string, required): Token symbol.

    • type (string, required): Token standard/type (e.g., ERC20).

    • id (string, optional): Token ID for NFTs or multi-tokens.

    • balance (string, required): Token balance of the account.

  • Usage: Part of Account schema to represent tokens held.

• Account
  Represents an EVM account with balances and tokens held.

  • Properties:

    • balance (string, required): Confirmed ETH (or native coin) balance.

    • unconfirmedBalance (string, required): Balance not yet confirmed on-chain.

    • pubkey (string, required): Account public address.

    • nonce (number, required): Transaction nonce for the account.

    • tokens (array of TokenBalance, required): Tokens held by the account.

  • Usage: Returned by /api/v1/account/{pubkey} endpoint.

• BadRequestError
  Error response for HTTP 400 Bad Request.

  • Properties:

    • error (string, required): Error message.

• ValidationError
  Error response for HTTP 422 Validation Error.

  • Properties:

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

    • details (object, required): Additional validation error details.

• InternalServerError
  Error response for HTTP 500 Internal Server Error.

  • Properties:

    • message (string, required): Error message.

• TokenTransfer
  Describes a token transfer event within a transaction.

  • Properties include token contract, decimals, name, symbol, type, optional token ID, and transfer details (from, to, value).

• InternalTx
  Represents internal (contract-level) transactions within an EVM transaction.

  • Properties:

    • from (string, required): Sender address.

    • to (string, required): Recipient address.

    • value (string, required): Amount transferred.

• Tx
  Represents an EVM transaction with detailed information.

  • Required properties: txid, blockHeight, timestamp, from, to, confirmations, value, fee, gasLimit, gasPrice, status.

  • Optional: blockHash, gasUsed, inputData, arrays of tokenTransfers and internalTxs.

• TxHistory (BaseTxHistory_Tx_)
  Paginated transaction history for an account.

  • Properties:

    • cursor (string, optional): Pagination cursor.

    • pubkey (string, required): Account address.

    • txs (array of Tx, required): Transactions in the current page.

• SendTxBody
  Request body for sending a raw transaction.

  • Properties:

    • hex (string, required): Serialized raw transaction hex string.

• RPCRequest
  JSON-RPC request format as per JSON-RPC 2.0 specification.

  • Properties:

    • jsonrpc (string, required, enum "2.0")

    • id (string or number, required)

    • method (string, required)

    • params (array, optional)

• RPCResponse
  JSON-RPC response format, including result or error.

  • Properties:

    • jsonrpc (string, required, enum "2.0")

    • id (string or number, required)

    • result (any, optional)

    • error (object with message and code, optional)

• TokenMetadata
  Metadata for tokens compliant with ERC-721 or ERC-1155 standards.

  • Properties:

    • name (string, required)

    • description (string, required)

    • media (object, required):

      • url (string, required)

      • type (string, enum ["image", "video"], optional)

• TokenType
  Enumeration of supported token types: "erc721", "erc1155".

• GasEstimate
  Estimated gas usage for a transaction.

  • Properties:

    • gasLimit (string, required)

• EstimateGasBody
  Request body for gas estimation.

  • Properties:

    • data (string, required): Transaction calldata.

    • from (string, required): Sender address.

    • to (string, required): Recipient address.

    • value (string, required): Amount of ETH/coin to send.

• Fees
  Fee details for legacy or EIP-1559 transactions.

  • Properties:

    • gasPrice (string, required)

    • maxFeePerGas (string, optional)

    • maxPriorityFeePerGas (string, optional)

• GasFees
  Recommended gas fees for different transaction speeds.

  • Properties:

    • baseFeePerGas (string, optional)

    • slow, average, fast (all Fees objects, required)

Paths and Operations

/api/v1/info — GetInfo (GET)

• Description: Returns basic information about the running coinstack (network).

• Response 200: Returns BaseInfo object, e.g., { "network": "mainnet" }.

• Security: None.

• Parameters: None.

/api/v1/account/{pubkey} — GetAccount (GET)

• Description: Retrieves detailed account information by address.

• Path Parameter:

  • pubkey (string, required): The account address.

• Responses:

  • 200: Returns Account object with balances and tokens.

  • 400: Returns BadRequestError.

  • 422: Returns ValidationError.

  • 500: Returns InternalServerError.

**Example Usage:**

GET /api/v1/account/0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF

/api/v1/account/{pubkey}/txs — GetTxHistory (GET)

• Description: Retrieves paginated transaction history for an account.

• Path Parameter:

  • pubkey (string, required): Account address.

• Query Parameters:

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

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

  • from (number, optional): Starting block number.

  • to (number, optional): Ending block number.

• Responses:

  • 200: Returns TxHistory object.

  • 400, 422, 500: Error responses.

/api/v1/tx/{txid} — GetTransaction (GET)

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

• Path Parameter:

  • txid (string, required): Transaction hash.

• Responses:

  • 200: Returns a Tx object.

  • 400, 422, 500: Error responses.

/api/v1/send — SendTx (POST)

• Description: Broadcasts a raw serialized transaction to the blockchain node.

• Request Body:

  • SendTxBody containing the hex string of the raw transaction.

• Responses:

  • 200: Returns the transaction ID (string).

  • 400, 422, 500: Error responses.

/api/v1/jsonrpc — DoRpcRequest (POST)

• Description: Sends JSON-RPC requests or batch requests to the node. Supports standard JSON-RPC 2.0 format.

• Request Body:

  • Single or array of RPCRequest objects.

• Response:

  • Single or array of RPCResponse objects.

• Example Request:

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

/api/v1/metadata/token — GetTokenMetadata (GET)

• Description: Retrieves metadata for a token (ERC-721 or ERC-1155).

• Query Parameters:

  • contract (string, required): Token contract address.

  • id (string, required): Token identifier.

  • type (TokenType, required): Token standard ("erc721" or "erc1155").

• Responses:

  • 200: Returns TokenMetadata object.

  • 422, 500: Error responses.

/api/v1/gas/estimate — EstimateGas (POST)

• Description: Estimates gas cost for a given transaction data.

• Request Body: EstimateGasBody containing transaction details (data, from, to, value).

• Response 200: Returns GasEstimate with gasLimit.

• Errors: 422, 500.

/api/v1/gas/fees — GetGasFees (GET)

• Description: Retrieves current recommended gas fees for transactions, including slow, average, and fast estimates.

• Response 200: Returns a GasFees object with fee recommendations in wei.

• Error: 500.

Important Implementation Details

• Strict Schema Validation: All objects disallow additional properties not explicitly defined, ensuring strict adherence to the schema.

• Pagination Support: Transaction history endpoint supports cursor-based pagination with optional filtering by block range and page size.

• JSON-RPC Proxying: The /api/v1/jsonrpc endpoint allows forwarding arbitrary JSON-RPC requests to the underlying blockchain node, enabling advanced interactions beyond standard REST endpoints.

• Token Metadata Handling: Supports fetching metadata for NFT standards ERC-721 and ERC-1155, including media URLs and types.

• Gas Fee Estimation: Provides both raw gas limit estimates and recommended transaction fees for different confirmation speeds, reflecting legacy and EIP-1559 fee models.

Interaction with Other System Components

• This API specification acts as the contract between the client applications (e.g., wallets, explorers, dApps) and the backend blockchain node interfaces.

• The API server implements these endpoints to communicate with BNB Smart Chain nodes or compatible EVM nodes, translating blockchain data and transactions into RESTful responses.

• The JSON-RPC endpoint forwards requests directly to the node, allowing clients to use JSON-RPC methods via HTTP REST interface.

• Token metadata endpoints may interact with external metadata storage or IPFS gateways to retrieve NFT details.

Visual Diagram

flowchart TD
    Info["GetInfo\n(GET /api/v1/info)"]
    Account["GetAccount\n(GET /api/v1/account/{pubkey})"]
    TxHistory["GetTxHistory\n(GET /api/v1/account/{pubkey}/txs)"]
    TxDetail["GetTransaction\n(GET /api/v1/tx/{txid})"]
    SendTx["SendTx\n(POST /api/v1/send)"]
    JsonRpc["DoRpcRequest\n(POST /api/v1/jsonrpc)"]
    TokenMeta["GetTokenMetadata\n(GET /api/v1/metadata/token)"]
    GasEstimate["EstimateGas\n(POST /api/v1/gas/estimate)"]
    GasFees["GetGasFees\n(GET /api/v1/gas/fees)"]

    Info -->|Returns BaseInfo| BaseInfo[BaseInfo Schema]
    Account -->|Returns Account| AccountSchema[Account Schema]
    TxHistory -->|Returns TxHistory| TxHistorySchema[TxHistory Schema]
    TxDetail -->|Returns Tx| TxSchema[Tx Schema]
    SendTx -->|Request: SendTxBody\nResponse: txid string| SendTxBodySchema[SendTxBody Schema]
    JsonRpc -->|Request: RPCRequest(s)\nResponse: RPCResponse(s)| RPCSchemas[RPCRequest & RPCResponse Schemas]
    TokenMeta -->|Returns TokenMetadata| TokenMetadataSchema[TokenMetadata Schema]
    GasEstimate -->|Request: EstimateGasBody\nResponse: GasEstimate| GasEstimateSchemas[EstimateGasBody & GasEstimate Schemas]
    GasFees -->|Returns GasFees| GasFeesSchema[GasFees Schema]

    classDef endpoint fill:#f9f,stroke:#333,stroke-width:1px,color:#000
    class Info,Account,TxHistory,TxDetail,SendTx,JsonRpc,TokenMeta,GasEstimate,GasFees endpoint

Summary

This [swagger.json](/projects/291/68851) is a robust and detailed OpenAPI definition for the Binance Smart Chain API, enabling developers to reliably integrate blockchain data retrieval, transaction processing, and gas fee management into their applications. It covers core blockchain interactions with strong schema validation and supports both REST and JSON-RPC protocols, facilitating flexible and comprehensive access to BNB Smart Chain features.