swagger.json

Overview

This file is an OpenAPI 3.0 specification document that defines the RESTful API for the [@shapeshiftoss/polygon-api](/projects/291/69128) project, version 10.0.0. The API provides programmatic access to Polygon (an EVM-compatible blockchain) coinstack data and operations, including account details, transaction history, transaction details, sending transactions, JSON-RPC calls, token metadata, and gas fee estimation.

The file serves as a formal contract describing the available endpoints, request and response schemas, error handling, and usage examples. It enables automatic generation of API client libraries, server stubs, and interactive documentation.

Detailed Explanation

Components

The [components](/projects/291/69205) section defines reusable schemas (data models) used throughout the API. These schemas describe the structure of request bodies and responses, including detailed property types, descriptions, required fields, and constraints.

Key schemas include:

• BaseInfo
  Contains base information about the running coinstack.
  Properties:

  • network (string) — The blockchain network name (e.g., "mainnet").

• TokenBalance
  Details about a token and its balance for an address.
  Properties:

  • contract (string) — Token contract address.

  • decimals (number) — Decimal precision.

  • name (string) — Token name.

  • symbol (string) — Token symbol.

  • type (string) — Token type (e.g., ERC20).

  • id (string, optional) — NFT or multi-token ID.

  • balance (string) — Token balance as a string.

• Account
  Information about an EVM account.
  Properties:

  • balance (string) — Confirmed balance.

  • unconfirmedBalance (string) — Unconfirmed balance.

  • pubkey (string) — Public address.

  • nonce (number) — Transaction count nonce.

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

• Tx
  Details about an EVM transaction.
  Properties include transaction hash, block info, timestamp, sender/recipient, confirmations, value, gas costs, status, input data, token transfers, and internal transactions.

• TokenTransfer and InternalTx
  Represent token transfer details and internal transactions within a transaction.

• RPCRequest and RPCResponse
  JSON-RPC 2.0 request and response formats used in the /api/v1/jsonrpc endpoint for generic node interactions.

• Errors
  Standardized error response schemas for 400 Bad Request, 422 Validation Error, and 500 Internal Server Error, each with descriptive messages.

• GasEstimate, EstimateGasBody, Fees, and GasFees
  Schemas related to gas cost estimation and fee recommendations, supporting both legacy and EIP-1559 transaction fee models.

• TokenMetadata
  Metadata for NFT tokens (ERC-721/ERC-1155), including name, description, and media information (image or video).

Paths (API Endpoints)

Each path corresponds to a RESTful endpoint with HTTP methods, request parameters, request body schemas, responses, and descriptions.

1. /api/v1/info (GET) — GetInfo

• Purpose: Retrieve basic information about the running coinstack.

• Response:

  • 200 OK with BaseInfo schema (e.g., network name).

• Usage Example:

  GET /api/v1/info
  

  Response:

  {
    "network": "mainnet"
  }
  

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

• Purpose: Get account details by address (public key).

• Parameters:

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

• Responses:

  • 200 OK with Account schema, including balance, nonce, and tokens.

  • 400, 422, 500 with appropriate error schemas.

• Example Response:

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

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

• Purpose: Retrieve paginated transaction history for an account.

• Parameters:

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

  • cursor (query, string, optional): Pagination cursor (base64 encoded JSON).

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

  • from (query, number, optional, default 0): Starting block number.

  • to (query, number, optional, default pending): Ending block number.

• Response:

  • 200 OK with TxHistory schema containing an array of Tx objects.

• Example:
  Fetch first 10 transactions from block 0 to latest for an address.

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

• Purpose: Retrieve details of a specific transaction by its hash.

• Parameters:

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

• Response:

  • 200 OK with Tx schema.

• Example:
  Fetch transaction details for a given hash.

5. /api/v1/send (POST) — SendTx

• Purpose: Broadcast a raw serialized transaction to the node.

• Request Body:

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

• Response:

  • 200 OK with transaction ID string.

• Usage Example:

  POST /api/v1/send
  Content-Type: application/json
  
  {
    "hex": "0xf86b808504a817c80082520894..."
  }
  

6. /api/v1/jsonrpc (POST) — DoRpcRequest

• Purpose: Forward JSON-RPC 2.0 requests or batch requests directly to the node.

• Request Body:

  • Single RPCRequest object or an array of RPCRequest objects.

• Response:

  • Single RPCResponse or array of RPCResponse objects.

• Usage Example:
  Request the current block number via JSON-RPC:

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

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

• Purpose: Retrieve metadata for a specific NFT token (ERC-721 or ERC-1155).

• Parameters:

  • contract (query, string, required): Contract address.

  • id (query, string, required): Token identifier.

  • type (query, TokenType enum, required): Token type (erc721 or erc1155).

• Response:

  • 200 OK with TokenMetadata schema.

• Example Response:

  {
    "name": "FoxyFox",
    "description": "FOXatars are a cyber-fox NFT project created by ShapeShift and Mercle",
    "media": {
      "url": "https://storage.mercle.xyz/ipfs/bafybeifihbavnaqwmisq72nwqpmxy3qkfqxj5nvjg7wimluhisp7wkzcru",
      "type": "image"
    }
  }
  

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

• Purpose: Estimate the gas cost for a transaction before sending.

• Request Body:

  • data (string): Transaction data payload (hex).

  • from (string): Sender address.

  • to (string): Recipient address.

  • value (string): Amount to send.

• Response:

  • 200 OK with GasEstimate schema containing gasLimit.

• Example Request:

  {
    "data": "0x",
    "from": "0x0000000000000000000000000000000000000000",
    "to": "0x3f758726E31b299Afb85b3D5C8B1fEc9b20b17cA",
    "value": "1337"
  }
  

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

• Purpose: Get current recommended gas fees for transactions, including estimates for slow, average, and fast confirmation speeds.

• Response:

  • 200 OK with GasFees schema, detailing baseFeePerGas and fees for different speeds.

• Notes:

  • For EIP-1559 transactions, use maxFeePerGas and maxPriorityFeePerGas.

  • For legacy transactions, use gasPrice.

Important Implementation Details

• Strict Schema Validation:
  Most schemas disallow additional properties ensuring strict adherence to defined formats.

• Pagination in Transaction History:
  The transaction history endpoint supports cursor-based pagination with base64 encoded cursors that contain paging state.

• JSON-RPC Proxying:
  The /api/v1/jsonrpc endpoint allows forwarding arbitrary JSON-RPC calls to the node, supporting both single and batch requests, enhancing flexibility for advanced users.

• Error Handling:
  Standardized error schemas (BadRequestError, ValidationError, InternalServerError) provide consistent error responses that clients can reliably parse.

• Token Metadata Support:
  Explicit support for ERC-721 and ERC-1155 token metadata including media type (image/video) helps integrate NFT display capabilities.

• Gas Estimation and Fee Recommendations:
  Supports both legacy gas pricing and EIP-1559 fee market, enabling clients to optimize gas usage according to the network state.

Interactions With Other System Components

• Blockchain Node:
  The API acts as an intermediary between clients and the Polygon blockchain node, exposing blockchain data and operations via HTTP REST and JSON-RPC.

• Client Applications:
  Wallets, explorers, and dApps interact with this API to fetch account balances, transaction history, send transactions, and query token metadata.

• Token Metadata Storage:
  Media URLs provided in token metadata suggest integration with decentralized storage (e.g., IPFS) or centralized media hosting for NFT assets.

• Transaction Broadcast:
  The /api/v1/send endpoint broadcasts raw transactions to the node, enabling clients to submit transactions without direct node access.

Usage Examples Summary

• Get network info:
  GET /api/v1/info → Returns current network (e.g., "mainnet").

• Get account details:
  GET /api/v1/account/0x123... → Returns balance, nonce, tokens.

• Get transaction history:
  GET /api/v1/account/0x123.../txs?pageSize=20 → Returns paginated tx history.

• Get transaction by hash:
  GET /api/v1/tx/0xabc... → Returns details of the transaction.

• Send raw transaction:
  POST /api/v1/send with { "hex": "0x..." } → Returns transaction ID.

• JSON-RPC call:
  POST /api/v1/jsonrpc with JSON-RPC request → Returns result.

• Get token metadata:
  GET /api/v1/metadata/token?contract=0x...&id=1&type=erc721 → Returns NFT metadata.

• Estimate gas:
  POST /api/v1/gas/estimate with tx data → Returns gas estimate.

• Get gas fees:
  GET /api/v1/gas/fees → Returns current recommended gas fees.

Visual Diagram: API Structure (Component Diagram)

flowchart TD
    subgraph Info
        A1[GET /api/v1/info]
    end

    subgraph Account
        A2[GET /api/v1/account/{pubkey}]
        A3[GET /api/v1/account/{pubkey}/txs]
    end

    subgraph Transaction
        A4[GET /api/v1/tx/{txid}]
        A5[POST /api/v1/send]
    end

    subgraph RPC
        A6[POST /api/v1/jsonrpc]
    end

    subgraph TokenMetadata
        A7[GET /api/v1/metadata/token]
    end

    subgraph Gas
        A8[POST /api/v1/gas/estimate]
        A9[GET /api/v1/gas/fees]
    end

    Client --> A1
    Client --> A2
    Client --> A3
    Client --> A4
    Client --> A5
    Client --> A6
    Client --> A7
    Client --> A8
    Client --> A9

    A5 -->|Broadcast Tx| Node
    A6 -->|JSON-RPC| Node
    A8 -->|Estimate Gas| Node
    A9 -->|Get Fees| Node
    A2 -->|Fetch Account Data| Node
    A3 -->|Fetch Tx History| Node
    A4 -->|Fetch Tx Details| Node
    A7 -->|Fetch Metadata| MetadataStorage

• Client: Any consumer of the API (wallets, explorers, dApps).

• Node: Polygon blockchain node providing blockchain data and transaction processing.

• MetadataStorage: External storage (e.g., IPFS) hosting NFT media assets.

Summary

The [swagger.json](/projects/291/68851) file comprehensively documents the Polygon API, specifying endpoints for blockchain data retrieval, transaction broadcasting, gas estimation, and token metadata. It uses detailed JSON schemas for robust data validation and includes extensive error handling. The API facilitates easy integration for developers building blockchain-enabled applications on Polygon, enabling both RESTful and JSON-RPC interactions. This specification enables automation in client/server code generation and API documentation tooling, ensuring consistency and maintainability across the project.