swagger.json

Overview

The [swagger.json](/projects/291/68851) file defines the OpenAPI 3.0 specification for the **@shapeshiftoss/arbitrum-nova-api**, version 10.0.0. This API provides a comprehensive interface to interact with the Arbitrum Nova blockchain coinstack, focusing on Ethereum Virtual Machine (EVM) compatible account and transaction operations.

The specification details the available RESTful endpoints, their request and response schemas, parameters, and error handling models. It enables clients to query blockchain state, retrieve account information, send transactions, estimate gas costs, and perform JSON-RPC calls to the underlying node.

This file is primarily used for:

• Generating client SDKs and server stubs.

• API documentation and exploration via tools like Swagger UI or Redoc.

• Validating API requests and responses against defined schemas.

• Serving as a contract between backend services and frontend or third-party clients.

Components

Schemas

The file defines multiple JSON schemas under [components/schemas](/projects/291/69205) that describe the data structures used in requests and responses.

BaseInfo

• Description: Contains base info about the running coinstack.

• Properties:

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

• Required: network

• Example:

  {
    "network": "mainnet"
  }
  

TokenBalance

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

• Properties:

  • contract (string) — Token contract address.

  • decimals (number) — Number of decimals.

  • 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) — Balance value as string.

• Required: All except id.

• Example:

  {
    "contract": "0x123...",
    "decimals": 18,
    "name": "FOX",
    "symbol": "FOX",
    "type": "ERC20",
    "balance": "1337"
  }
  

Account

• Description: Contains info about an EVM account.

• Properties:

  • balance (string) — Confirmed balance.

  • unconfirmedBalance (string) — Unconfirmed balance.

  • pubkey (string) — Account address.

  • nonce (number) — Transaction nonce.

  • tokens (array of TokenBalance) — Tokens held by the account.

• Required: All properties.

• Example:

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

BadRequestError

• Description: Represents a 400 Bad Request error.

• Properties:

  • error (string) — Error message.

• Required: error

ValidationError

• Description: Represents a 422 Validation Error response.

• Properties:

  • message (string) — Fixed value: "Validation failed".

  • details (object) — Additional validation error details.

• Required: message, details

InternalServerError

• Description: Represents a 500 Internal Server Error.

• Properties:

  • message (string) — Error message.

• Required: message

TokenTransfer

• Description: Contains token transfer details.

• Properties:

  • contract, decimals, name, symbol, type, id (optional) — Token info.

  • from (string) — Sender address.

  • to (string) — Recipient address.

  • value (string) — Transferred amount.

• Required: All except id.

InternalTx

• Description: Details of an internal transaction within EVM.

• Properties:

  • from (string) — Sender address.

  • to (string) — Recipient address.

  • value (string) — Amount transferred.

• Required: All properties.

Tx

• Description: Information about an EVM transaction.

• Properties:

  • txid, blockHash, blockHeight, timestamp, from, to, confirmations, value, fee, gasLimit, gasUsed, gasPrice, status, inputData (optional)

  • tokenTransfers (array of TokenTransfer)

  • internalTxs (array of InternalTx)

• Required: Most transaction metadata fields.

BaseTxHistory_Tx_

• Description: Paginated base transaction history.

• Properties:

  • cursor (string, optional) — Pagination cursor.

  • pubkey (string) — Account address.

  • txs (array of Tx) — Transactions.

• Required: pubkey, txs

TxHistory

• Alias of BaseTxHistory_Tx_ with description about EVM transaction history.

SendTxBody

• Description: Serialized raw transaction hex.

• Properties:

  • hex (string) — Raw transaction data.

• Required: hex

RPCRequest & RPCResponse

• RPCRequest: JSON-RPC 2.0 request with jsonrpc, id, method, params.

• RPCResponse: JSON-RPC 2.0 response with jsonrpc, id, result, or error.

TokenMetadata

• Description: ERC-721/ERC-1155 token metadata.

• Properties:

  • name (string)

  • description (string)

  • media (object)

    • url (string)

    • type (string enum: image or video)

• Required: All properties.

TokenType

• Description: Supported token types.

• Enum: "erc721", "erc1155"

GasEstimate

• Description: Estimated gas limit for a transaction.

• Properties:

  • gasLimit (string)

• Required: gasLimit

EstimateGasBody

• Description: Transaction data for gas estimation.

• Properties:

  • data (string)

  • from (string)

  • to (string)

  • value (string)

• Required: All properties.

Fees

• Description: Legacy/EIP-1559 fee details.

• Properties:

  • gasPrice (string)

  • maxFeePerGas (string, optional)

  • maxPriorityFeePerGas (string, optional)

• Required: gasPrice

GasFees

• Description: Recommended current gas fees.

• Properties:

  • baseFeePerGas (string, optional)

  • slow, average, fast (all of type Fees)

• Required: slow, average, fast

Paths (Endpoints)

/api/v1/info [GET]

• OperationId: GetInfo

• Description: Retrieves information about the running coinstack.

• Response 200: Returns BaseInfo schema.

• Usage Example:

  curl GET /api/v1/info
  # Response:
  # { "network": "mainnet" }
  

/api/v1/account/{pubkey} [GET]

• OperationId: GetAccount

• Description: Fetch account details by EVM address.

• Parameters:

  • pubkey (string, path) — Account address.

• Responses:

  • 200: Returns Account info.

  • 400: BadRequestError

  • 422: ValidationError

  • 500: InternalServerError

• Usage Example:

  curl GET /api/v1/account/0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF
  

/api/v1/account/{pubkey}/txs [GET]

• OperationId: GetTxHistory

• Description: Retrieves paginated transaction history for an account.

• Parameters:

  • pubkey (string, path) — Account address.

  • cursor (string, query, optional) — Pagination cursor.

  • pageSize (number, query, optional, default 10) — Number of txs per page.

  • from (number, query, optional) — Start block number.

  • to (number, query, optional) — End block number.

• Responses:

  • 200: Returns TxHistory.

  • 400, 422, 500: Error schemas.

• Usage Example:

  curl GET /api/v1/account/0xAddress/txs?pageSize=20&from=1000000&to=latest
  

/api/v1/tx/{txid} [GET]

• OperationId: GetTransaction

• Description: Get detailed transaction info by hash.

• Parameters:

  • txid (string, path) — Transaction hash.

• Responses:

  • 200: Tx schema.

  • 400, 422, 500: Error schemas.

• Usage Example:

  curl GET /api/v1/tx/0xTransactionHash
  

/api/v1/send [POST]

• OperationId: SendTx

• Description: Broadcast a raw serialized transaction hex to the node.

• Request Body: SendTxBody with hex string.

• Responses:

  • 200: Transaction ID (string).

  • 400, 422, 500: Errors.

• Usage Example:

  curl -X POST /api/v1/send -d '{"hex":"0x..."}' -H "Content-Type: application/json"
  

/api/v1/jsonrpc [POST]

• OperationId: DoRpcRequest

• Description: Perform JSON-RPC requests (single or batch) to the blockchain node.

• Request Body: RPCRequest or array of RPCRequest.

• Responses:

  • 200: RPCResponse or array of RPCResponse.

• Usage Example:

  curl -X POST /api/v1/jsonrpc -d '{"jsonrpc":"2.0","id":"1","method":"eth_blockNumber","params":[]}' -H "Content-Type: application/json"
  

/api/v1/metadata/token [GET]

• OperationId: GetTokenMetadata

• Description: Retrieve metadata of a token (ERC721 or ERC1155).

• Parameters:

  • contract (string, query) — Token contract address.

  • id (string, query) — Token identifier.

  • type (TokenType, query) — Token type enum.

• Responses:

  • 200: TokenMetadata.

  • 422, 500: Errors.

• Usage Example:

  curl GET "/api/v1/metadata/token?contract=0x...&id=1&type=erc721"
  

/api/v1/gas/estimate [POST]

• OperationId: EstimateGas

• Description: Estimate gas limit for a transaction.

• Request Body: EstimateGasBody containing data, from, to, value.

• Responses:

  • 200: GasEstimate.

  • 422, 500: Errors.

• Usage Example:

  curl -X POST /api/v1/gas/estimate -d '{"data":"0x","from":"0x...","to":"0x...","value":"1337"}' -H "Content-Type: application/json"
  

/api/v1/gas/fees [GET]

• OperationId: GetGasFees

• Description: Get current recommended gas fees for slow, average, and fast confirmation speeds.

• Responses:

  • 200: GasFees.

  • 500: Internal Server Error.

• Usage Notes:

  • Use maxFeePerGas and maxPriorityFeePerGas for EIP-1559 transactions.

  • Use gasPrice for legacy transactions.

• Usage Example:

  curl GET /api/v1/gas/fees
  

Important Implementation Details

• Strict Schema Validation: All request and response bodies disallow additional properties (additionalProperties: false) to ensure strict conformity.

• Error Handling: The API consistently defines common HTTP error responses (400, 422, 500) with descriptive schemas to help clients diagnose issues.

• Pagination: Transaction history supports cursor-based pagination via a base64 encoded cursor string, enabling efficient data retrieval.

• JSON-RPC Proxying: The /api/v1/jsonrpc endpoint allows clients to send arbitrary JSON-RPC calls (including batch requests) directly to the node, providing flexibility beyond REST endpoints.

• Token Metadata Support: Supports ERC-721 and ERC-1155 token types, including media attachments (image/video) for NFTs.

• Gas Fee Estimation: Provides both gas cost estimation and recommended fee tiers to adapt to network conditions, supporting legacy and EIP-1559 fee models.

Integration and Interactions

• This API specification serves as the contract for the Arbitrum Nova blockchain coinstack backend.

• Client applications (wallets, explorers, dApps) interact with this API to query blockchain state, send transactions, and estimate fees.

• The JSON-RPC endpoint interacts directly with the underlying Ethereum node or node cluster.

• Token metadata retrieval likely integrates with off-chain storage or IPFS gateways (as indicated by media URLs).

• The gas fees endpoint reflects real-time network conditions, potentially sourced from blockchain fee oracles or node data.

• Transaction data and account state are sourced from the node's blockchain database and mempool.

Mermaid Flowchart Diagram

The following flowchart illustrates the primary REST API endpoints and their relationships with key data schemas and operations:

flowchart TD
    Info["GET /api/v1/info"]
    Account["GET /api/v1/account/{pubkey}"]
    TxHistory["GET /api/v1/account/{pubkey}/txs"]
    TxDetail["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"]

    Info -->|returns| BaseInfo["BaseInfo"]
    Account -->|returns| AccountSchema["Account"]
    TxHistory -->|returns| TxHistorySchema["TxHistory"]
    TxDetail -->|returns| TxSchema["Tx"]
    SendTx -->|accepts| SendTxBody["SendTxBody"]
    SendTx -->|returns| TxId["Transaction ID (string)"]
    JsonRpc -->|accepts| RPCRequest["RPCRequest or batch"]
    JsonRpc -->|returns| RPCResponse["RPCResponse or batch"]
    TokenMeta -->|returns| TokenMetadataSchema["TokenMetadata"]
    GasEstimate -->|accepts| EstimateGasBodySchema["EstimateGasBody"]
    GasEstimate -->|returns| GasEstimateSchema["GasEstimate"]
    GasFees -->|returns| GasFeesSchema["GasFees"]

    %% Error responses shared by many endpoints
    Error400["400 BadRequestError"]
    Error422["422 ValidationError"]
    Error500["500 InternalServerError"]

    Account -->|errors| Error400
    Account -->|errors| Error422
    Account -->|errors| Error500

    TxHistory -->|errors| Error400
    TxHistory -->|errors| Error422
    TxHistory -->|errors| Error500

    TxDetail -->|errors| Error400
    TxDetail -->|errors| Error422
    TxDetail -->|errors| Error500

    SendTx -->|errors| Error400
    SendTx -->|errors| Error422
    SendTx -->|errors| Error500

    TokenMeta -->|errors| Error422
    TokenMeta -->|errors| Error500

    GasEstimate -->|errors| Error422
    GasEstimate -->|errors| Error500

    GasFees -->|errors| Error500

Summary

This [swagger.json](/projects/291/68851) OpenAPI specification precisely defines the REST endpoints and data models for interacting with the Arbitrum Nova EVM-compatible blockchain node. It enables querying account balances, transaction histories, transaction details, sending raw transactions, calling JSON-RPC methods, retrieving token metadata, and managing gas fee estimations.

The strict schema definitions and standardized error handling ensure robust client-server integration, while endpoints like JSON-RPC proxying and token metadata enrich the API's flexibility and utility for diverse blockchain applications.

End of Documentation for swagger.json