swagger.json

Overview

This file is an OpenAPI 3.0 specification document describing the REST API for the [@shapeshiftoss/avalanche-api](/projects/291/68873) version 10.0.0. It defines a comprehensive interface for interacting with an Avalanche-based blockchain coinstack, exposing endpoints to retrieve network and account information, transaction details and history, send transactions, query gas fees and estimates, obtain token metadata, and perform JSON-RPC calls to the underlying node.

The API supports typical blockchain explorer and wallet functionalities targeted at Ethereum Virtual Machine (EVM) compatible chains on Avalanche. It provides strongly typed JSON schemas for request and response payloads, error handling, and supports both single and batch JSON-RPC requests.

Detailed Documentation

Components

The specification defines multiple JSON schemas under [components.schemas](/projects/291/69205) which are reused throughout the API. These schemas represent data models for accounts, transactions, token balances, errors, gas fees, and RPC communication.

Key Schemas

BaseInfo
- Purpose: Provides basic information about the running coinstack.
- Properties:
  - network (string, required): Name of the network, e.g., "mainnet".
- Usage: Returned by /api/v1/info GET endpoint.
- Example:
```
{
  "network": "mainnet"
}
```
TokenBalance
- Purpose: Represents token details and balance associated with an address.
- 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 standard/type (e.g., ERC20).
  - id (string, optional): NFT or multi-token identifier.
  - balance (string): Token balance in string format.
- Usage: Used inside Account.tokens array.
Account
- Purpose: Provides detailed EVM account information.
- Properties:
  - balance (string): Confirmed balance.
  - unconfirmedBalance (string): Unconfirmed balance.
  - pubkey (string): Account address/public key.
  - nonce (number): Transaction nonce.
  - tokens (TokenBalance[]): List of tokens owned.
- Usage: Returned by /api/v1/account/{pubkey} GET endpoint.
- Example:
```
{
  "balance": "0",
  "unconfirmedBalance": "0",
  "nonce": 0,
  "pubkey": "0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF",
  "tokens": [
    {
      "balance": "1337",
      "contract": "0xc770EEfAd204B5180dF6a14Ee197D99d808ee52d",
      "decimals": 18,
      "name": "FOX",
      "symbol": "FOX",
      "type": "ERC20"
    }
  ]
}
```
Tx (Transaction)
- Purpose: Holds detailed information about an EVM transaction.
- Properties include:
  - txid (string): Transaction hash.
  - blockHash (string), blockHeight (number), timestamp (number).
  - from, to (string): Addresses.
  - confirmations (number): Number of confirmations.
  - value, fee, gasLimit, gasUsed, gasPrice (string).
  - status (number): Transaction status code.
  - inputData (string): Hex-encoded input data.
  - tokenTransfers (array of TokenTransfer): Token transfer details.
  - internalTxs (array of InternalTx): Internal transaction details.
- Usage: Returned by /api/v1/tx/{txid} GET endpoint and transaction history endpoints.
TokenTransfer
- Purpose: Details of a token transfer within a transaction.
- Properties include contract, decimals, name, symbol, type, id, from, to, and value.
InternalTx
- Purpose: Represents internal EVM transactions (calls within a transaction).
- Properties:
  - from, to (string): Addresses.
  - value (string): Amount transferred.
TxHistory
- Purpose: Paginated transaction history for a given account.
- Properties:
  - pubkey (string): Account address.
  - txs (array of Tx): List of transactions.
  - cursor (string, optional): Cursor for pagination.
SendTxBody
- Purpose: Request body for sending a raw transaction.
- Properties:
  - hex (string, required): Serialized raw transaction hex string.
- Usage: Used in POST /api/v1/send.
RPCRequest / RPCResponse
- Purpose: Define JSON-RPC 2.0 request and response objects.
- Support batch requests (array of RPCRequest) and responses.
- Used in POST /api/v1/jsonrpc endpoint.
TokenMetadata
- Purpose: Metadata for NFTs or tokens (ERC-721/ERC-1155).
- Properties:
  - name, description (string).
  - media: Object with url (string) and type ("image" or "video").
- Usage: Returned by /api/v1/metadata/token.
GasEstimate / EstimateGasBody
- Purpose: Request and response schemas for gas estimation.
- Contains gas limit as string.
- Used in POST /api/v1/gas/estimate.
Fees / GasFees
- Purpose: Represents legacy or EIP-1559 gas fee parameters.
- GasFees includes base fee and recommended fee levels (slow, average, fast).
- Used in GET /api/v1/gas/fees.
Error Schemas
- BadRequestError, ValidationError, InternalServerError:
  - Standardized error responses for 400, 422, 500 HTTP status codes.

Paths (Endpoints)

1. GET /api/v1/info

Description: Retrieve basic coinstack network information.
Response: BaseInfo
Example Usage:
```
curl GET /api/v1/info
```

2. GET /api/v1/account/{pubkey}

Description: Fetch account details by public key (address).
Parameters:
- pubkey (string, path, required): Account address.
Response: Account
Errors: 400, 422, 500 with respective error schemas.

3. GET /api/v1/account/{pubkey}/txs

Description: Get paginated transaction history for an account.
Parameters:
- pubkey (string, path, required)
- cursor (string, query, optional): Pagination cursor.
- pageSize (number, query, optional, default 10)
- from (number, query, optional): From block number.
- to (number, query, optional): To block number.
Response: TxHistory
Errors: 400, 422, 500.

4. GET /api/v1/tx/{txid}

Description: Get detailed information on a specific transaction.
Parameters:
- txid (string, path, required): Transaction hash.
Response: Tx
Errors: 400, 422, 500.

5. POST /api/v1/send

Description: Broadcast a serialized raw transaction to the node.
Request Body:
- SendTxBody containing raw transaction hex string.
Response: Transaction ID as string.
Errors: 400, 422, 500.

6. POST /api/v1/jsonrpc

Description: Make a JSON-RPC call or batch calls to the node.
Request Body: Single or array of RPCRequest.
Response: Single or array of RPCResponse.

Example:

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

7. GET /api/v1/metadata/token

Description: Retrieve metadata for a specific token (NFT).
Query Parameters:
- contract (string, required): Token contract address.
- id (string, required): Token identifier.
- type (TokenType enum: "erc721" or "erc1155", required)
Response: TokenMetadata.
Errors: 422, 500.

8. POST /api/v1/gas/estimate

Description: Estimate gas limit for a transaction.
Request Body: EstimateGasBody with transaction data.
Response: GasEstimate.
Errors: 422, 500.

9. GET /api/v1/gas/fees

Description: Get current recommended gas fees for different confirmation speeds.
Response: GasFees.
Errors: 500.

Implementation Details & Algorithms

The API uses standard REST conventions with resource-oriented endpoints.
Pagination for transaction history is cursor-based, using a base64 encoded JSON cursor to fetch pages.
JSON-RPC 2.0 support allows direct interaction with the EVM node, including batch requests.
Gas fee recommendations provide both legacy (gasPrice) and EIP-1559 (maxFeePerGas, maxPriorityFeePerGas) fields to support different transaction types.
Token metadata retrieval supports ERC-721 and ERC-1155 standards, providing media URLs for NFT display.
Error handling is standardized with descriptive schemas to facilitate client error processing.
All monetary values (balances, fees, gas prices) are represented as strings to preserve precision and avoid floating-point issues.

Interaction with Other System Parts

This API acts as the backend interface for wallet applications, explorers, or other client software interacting with the Avalanche EVM coinstack.
It likely interfaces with blockchain node(s) to fetch on-chain data, send transactions, and query state.
The JSON-RPC endpoint proxies raw JSON-RPC calls directly to the underlying node(s).
Token metadata may be retrieved from decentralized storage or off-chain services linked via contract addresses and token IDs.
Gas fee estimations and recommendations are presumably calculated or fetched from node or external fee oracles.
The modular schema definitions ensure easy integration and validation across client and server implementations.
Client apps can use this API to build user interfaces for account overview, transaction history, token management, and transaction crafting.

Visual Diagram: Component Diagram of Main API Endpoints and Schemas

flowchart TD
    Info["GET /api/v1/info<br/>Returns BaseInfo"]
    Account["GET /api/v1/account/{pubkey}<br/>Returns Account"]
    TxHistory["GET /api/v1/account/{pubkey}/txs<br/>Returns TxHistory"]
    TxDetail["GET /api/v1/tx/{txid}<br/>Returns Tx"]
    SendTx["POST /api/v1/send<br/>SendTxBody -> string(txid)"]
    JsonRpc["POST /api/v1/jsonrpc<br/>RPCRequest -> RPCResponse"]
    TokenMeta["GET /api/v1/metadata/token<br/>Returns TokenMetadata"]
    GasEstimate["POST /api/v1/gas/estimate<br/>EstimateGasBody -> GasEstimate"]
    GasFees["GET /api/v1/gas/fees<br/>Returns GasFees"]

    Info --> BaseInfo[BaseInfo Schema]
    Account --> AccountSchema[Account Schema]
    AccountSchema --> TokenBalanceSchema[TokenBalance Schema]
    TxHistory --> TxHistorySchema[TxHistory Schema]
    TxHistorySchema --> TxSchema[Tx Schema]
    TxSchema --> TokenTransferSchema[TokenTransfer Schema]
    TxSchema --> InternalTxSchema[InternalTx Schema]
    TxDetail --> TxSchema
    SendTx --> SendTxBody[SendTxBody Schema]
    JsonRpc --> RPCRequest[RPCRequest Schema]
    JsonRpc --> RPCResponse[RPCResponse Schema]
    TokenMeta --> TokenMetadataSchema[TokenMetadata Schema]
    GasEstimate --> EstimateGasBody[EstimateGasBody Schema]
    GasEstimate --> GasEstimateSchema[GasEstimate Schema]
    GasFees --> GasFeesSchema[GasFees Schema]

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

Usage Examples

Example: Fetching Account Details

curl -X GET "https://api.example.com/api/v1/account/0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF"

Response:

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

Example: Sending a Raw Transaction

curl -X POST "https://api.example.com/api/v1/send" \
  -H "Content-Type: application/json" \
  -d '{
    "hex": "0xf86b808504a817c80082520894..."
  }'

Response:

"0x123456789abcdef..."

Example: JSON-RPC Call

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

Response:

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

Summary

This OpenAPI specification defines a rich, well-typed, and robust RESTful API for interacting with the Avalanche EVM coinstack. It covers all essential blockchain operations such as querying accounts, transactions, sending transactions, gas fee estimation, and token metadata retrieval. The inclusion of a JSON-RPC proxy endpoint enables full node interaction, while detailed schema definitions enhance client integration and validation.

This file is a core part of the backend API layer in the overall architecture, serving as the contract between frontend clients and blockchain node interactions.

End of Documentation for `swagger.json`

swagger.json

Overview

Detailed Documentation

Components

Key Schemas

Paths (Endpoints)

1. GET /api/v1/info

2. GET /api/v1/account/{pubkey}

3. GET /api/v1/account/{pubkey}/txs

4. GET /api/v1/tx/{txid}

5. POST /api/v1/send

6. POST /api/v1/jsonrpc

7. GET /api/v1/metadata/token

8. POST /api/v1/gas/estimate

9. GET /api/v1/gas/fees

Implementation Details & Algorithms

Interaction with Other System Parts

Visual Diagram: Component Diagram of Main API Endpoints and Schemas

Usage Examples

Example: Fetching Account Details

Example: Sending a Raw Transaction

Example: JSON-RPC Call

Summary

End of Documentation for swagger.json

End of Documentation for `swagger.json`