swagger.json

Overview

[swagger.json](/projects/291/68851) is an OpenAPI 3.0 specification document that defines the REST API for the [@shapeshiftoss/arbitrum-api](/projects/291/69034) project, version 10.0.0. This API primarily exposes endpoints to interact with an Arbitrum-based EVM-compatible blockchain node, enabling clients to:

Retrieve blockchain network info
Query account balances and token holdings
Fetch transaction details and history
Broadcast raw transactions
Perform JSON-RPC calls to the node
Obtain token metadata (ERC-721/ERC-1155)
Estimate gas costs and get recommended gas fees for transactions

This specification serves as a contract for client-server communication, detailing request formats, response schemas, error handling, and endpoint paths. It is used to generate client SDKs, API documentation, and server stubs, facilitating integration with the Arbitrum blockchain services.

Detailed Explanation of Components

Components

The file defines reusable **schemas** (data models) that describe the structure of API request and response payloads. These schemas ensure consistency across endpoints.

Schemas

1. BaseInfo

Purpose: Contains base information about the running coinstack/network.
Properties:
- network (string, required): The network name (e.g., "mainnet").
Example:
```
{
  "network": "mainnet"
}
```
Usage: Returned by GET /api/v1/info.

2. TokenBalance

Purpose: Represents token information including balance for an address.
Properties:
- contract (string, required): Token contract address.
- decimals (number, required): Number of decimals for the token.
- name (string, required): Token name.
- symbol (string, required): Token symbol.
- type (string, required): Token type (e.g., "ERC20").
- id (string, optional): NFT or multi-token ID.
- balance (string, required): Token balance as a string.

Example:

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

Usage: Used within Account.tokens.

3. Account

Purpose: Represents an EVM account details.
Properties:
- balance (string, required): Confirmed balance.
- unconfirmedBalance (string, required): Unconfirmed balance.
- pubkey (string, required): Account address.
- nonce (number, required): Transaction nonce.
- tokens (array of TokenBalance, required): Tokens held by the account.

Example:

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

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

4. Transaction Related Schemas

TokenTransfer: Token transfer details within a transaction.
InternalTx: Internal transaction info between addresses.
Tx: Comprehensive EVM transaction details including token transfers and internal transactions.
BaseTxHistory_Tx_: Paginated transaction history holding an array of Tx objects along with pagination cursor.
TxHistory: Alias to BaseTxHistory_Tx_.

**Key properties of `Tx`:**

txid: Transaction hash.
blockHash: Block hash containing the transaction.
blockHeight: Block number.
timestamp: UNIX timestamp.
from, to: Addresses involved.
confirmations: Number of confirmations.
value: Transferred value.
fee, gasLimit, gasUsed, gasPrice: Gas and fee details.
status: Transaction status (e.g., 1 for success).
inputData: Hex encoded input data.
tokenTransfers: List of token transfers.
internalTxs: List of internal transactions.

**Usage:**

GET /api/v1/tx/{txid} returns a Tx.
GET /api/v1/account/{pubkey}/txs returns TxHistory.

5. Error Schemas

BadRequestError: For HTTP 400 errors, with an error string.
ValidationError: For HTTP 422 validation failures, containing a fixed message "Validation failed" and a details object.
InternalServerError: For HTTP 500 errors, with a message string.

6. SendTxBody

Purpose: Holds the serialized raw transaction hex for broadcasting.
Properties:
- hex (string, required): Raw transaction hex string.
Usage: Request body for POST /api/v1/send.

7. RPCRequest and RPCResponse

RPCRequest: JSON-RPC 2.0 request format.
RPCResponse: JSON-RPC 2.0 response format, including error object if present.

**Usage:** Used by `POST /api/v1/jsonrpc` to make arbitrary JSON-RPC calls or batch calls to the node.

8. TokenMetadata and TokenType

TokenMetadata: Metadata for NFTs (ERC-721/ERC-1155) including name, description, and media.
TokenType: Enum of "erc721" or "erc1155".

**Usage:** Returned by `GET /api/v1/metadata/token`.

9. GasEstimate and EstimateGasBody

GasEstimate: Estimated gas limit for a transaction.
EstimateGasBody: Transaction data required to estimate gas (data, from, to, value).

**Usage:** Request/response for `POST /api/v1/gas/estimate`.

10. Fees and GasFees

Fees: Contains legacy and EIP-1559 fee details, e.g., gasPrice, maxFeePerGas, maxPriorityFeePerGas.
GasFees: Aggregates current recommended fees for slow, average, and fast confirmations, including base fee.

**Usage:** Returned by `GET /api/v1/gas/fees`.

Paths (Endpoints)

Each path defines HTTP methods, parameters, request bodies, responses, and descriptions.

1. `/api/v1/info` [GET]

Retrieves coinstack/network info.
Response: BaseInfo
Example: { "network": "mainnet" }

2. `/api/v1/account/{pubkey}` [GET]

Retrieves account details by Ethereum address (pubkey).
Path Parameter:
- pubkey (string): Account address.
Response: Account
Possible errors: 400, 422, 500

3. `/api/v1/account/{pubkey}/txs` [GET]

Retrieves paginated transaction history for an account.
Path Parameter:
- pubkey (string): Account address.
Query Parameters:
- cursor (string, optional): Pagination cursor.
- pageSize (number, optional): Number of results per page (default 10).
- from (number, optional): Starting block number.
- to (number, optional): Ending block number.
Response: TxHistory
Possible errors: 400, 422, 500

4. `/api/v1/tx/{txid}` [GET]

Retrieves transaction details by transaction hash.
Path Parameter:
- txid (string): Transaction hash.
Response: Tx
Possible errors: 400, 422, 500

5. `/api/v1/send` [POST]

Broadcasts a raw serialized transaction.
Request Body: SendTxBody (contains raw hex string)
Response: Transaction ID string
Possible errors: 400, 422, 500

6. `/api/v1/jsonrpc` [POST]

Makes a JSON-RPC request or batch requests to the node.
Request Body: RPCRequest or array of RPCRequest.
Response: RPCResponse or array of RPCResponse.

7. `/api/v1/metadata/token` [GET]

Retrieves token metadata for NFTs.
Query Parameters:
- contract (string, required): Contract address.
- id (string, required): Token ID.
- type (TokenType, required): Token type (erc721 or erc1155).
Response: TokenMetadata
Possible errors: 422, 500

8. `/api/v1/gas/estimate` [POST]

Estimates gas cost for a transaction.
Request Body: EstimateGasBody
Response: GasEstimate
Possible errors: 422, 500

9. `/api/v1/gas/fees` [GET]

Retrieves current recommended gas fees (slow, average, fast).
Response: GasFees
Possible errors: 500

Important Implementation Details and Algorithms

Pagination: Transaction history endpoint uses a cursor parameter encoded in base64 representing pagination state, enabling efficient paging through large transaction sets.
Token Types: Supports both fungible tokens (ERC-20) and NFTs (ERC-721 and ERC-1155), with separate metadata retrieval for NFTs.
Gas Fee Recommendations: Provides EIP-1559 style fee estimates with separate tiers for confirmation speed.
JSON-RPC Proxy: The /jsonrpc endpoint allows clients to send arbitrary JSON-RPC calls or batches, enabling flexibility beyond predefined REST endpoints.
Strict Schema Validation: All schemas disallow additional properties, enforcing strict adherence to the defined API contract.

Interaction with Other Parts of the System

The API acts as an interface layer between clients (frontend apps, wallets, other services) and the Arbitrum blockchain node.
The JSON-RPC endpoint directly proxies calls to the underlying node, while other endpoints aggregate or transform data for client consumption.
Token metadata retrieval likely interfaces with off-chain metadata services or IPFS gateways.
Gas estimation and fee recommendation endpoints rely on node state and possibly external gas price oracles.
The /send endpoint broadcasts raw transactions to the node, integrating with the blockchain mempool.

Usage Examples

Get Account Details

Request:

GET /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"
    }
  ]
}

Send Raw Transaction

Request:

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

{
  "hex": "0xf86c808504a817c80082520894..."
}

Response:

"0x123abc..."  // Transaction hash string

Visual Diagram

Below is a Mermaid class diagram representing the key schemas and their relationships in this API specification:

classDiagram
    class BaseInfo {
        +string network
    }

    class TokenBalance {
        +string contract
        +number decimals
        +string name
        +string symbol
        +string type
        +string id
        +string balance
    }

    class Account {
        +string balance
        +string unconfirmedBalance
        +string pubkey
        +number nonce
        +TokenBalance[] tokens
    }

    class TokenTransfer {
        +string contract
        +number decimals
        +string name
        +string symbol
        +string type
        +string id
        +string from
        +string to
        +string value
    }

    class InternalTx {
        +string from
        +string to
        +string value
    }

    class Tx {
        +string txid
        +string blockHash
        +number blockHeight
        +number timestamp
        +string from
        +string to
        +number confirmations
        +string value
        +string fee
        +string gasLimit
        +string gasUsed
        +string gasPrice
        +number status
        +string inputData
        +TokenTransfer[] tokenTransfers
        +InternalTx[] internalTxs
    }

    class BaseTxHistory_Tx_ {
        +string cursor
        +string pubkey
        +Tx[] txs
    }

    class SendTxBody {
        +string hex
    }

    class RPCRequest {
        +string jsonrpc
        +string id
        +string method
        +any[] params
    }

    class RPCResponse {
        +string jsonrpc
        +string id
        +any result
        +Error error
    }

    class TokenMetadata {
        +string name
        +string description
        +Media media
    }

    class Media {
        +string type
        +string url
    }

    class GasEstimate {
        +string gasLimit
    }

    class EstimateGasBody {
        +string data
        +string from
        +string to
        +string value
    }

    class Fees {
        +string gasPrice
        +string maxFeePerGas
        +string maxPriorityFeePerGas
    }

    class GasFees {
        +string baseFeePerGas
        +Fees slow
        +Fees average
        +Fees fast
    }

    Account --> "tokens" TokenBalance
    Tx --> "tokenTransfers" TokenTransfer
    Tx --> "internalTxs" InternalTx
    BaseTxHistory_Tx_ --> "txs" Tx
    RPCResponse --> Error
    TokenMetadata --> Media
    GasFees --> Fees

Summary

This [swagger.json](/projects/291/68851) file is a comprehensive OpenAPI specification for the Arbitrum blockchain API provided by ShapeShift. It enables standardized access to blockchain data, transactions, tokens, and gas fee information, supporting both REST and JSON-RPC paradigms. The detailed schemas, error models, and path definitions facilitate reliable client integration and streamline blockchain interactions.

swagger.json

Overview

Detailed Explanation of Components

Components

Schemas

1. BaseInfo

2. TokenBalance

3. Account

4. Transaction Related Schemas

5. Error Schemas

6. SendTxBody

7. RPCRequest and RPCResponse

8. TokenMetadata and TokenType

9. GasEstimate and EstimateGasBody

10. Fees and GasFees

Paths (Endpoints)

1. /api/v1/info [GET]

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

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

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

5. /api/v1/send [POST]

6. /api/v1/jsonrpc [POST]

7. /api/v1/metadata/token [GET]

8. /api/v1/gas/estimate [POST]

9. /api/v1/gas/fees [GET]

Important Implementation Details and Algorithms

Interaction with Other Parts of the System

Usage Examples

Get Account Details

Send Raw Transaction

Visual Diagram

Summary

1. `/api/v1/info` [GET]

2. `/api/v1/account/{pubkey}` [GET]

3. `/api/v1/account/{pubkey}/txs` [GET]

4. `/api/v1/tx/{txid}` [GET]

5. `/api/v1/send` [POST]

6. `/api/v1/jsonrpc` [POST]

7. `/api/v1/metadata/token` [GET]

8. `/api/v1/gas/estimate` [POST]

9. `/api/v1/gas/fees` [GET]