swagger.json

Overview

This file is an OpenAPI 3.0 specification document defining the RESTful API for the **@shapeshiftoss/ethereum-api** project (version 10.0.0). It describes the endpoints, request/response schemas, and operations for interacting with an Ethereum-compatible blockchain coinstack.

The API provides functionality for:

Retrieving coinstack information
Querying EVM account details and transaction history
Fetching transaction details by hash
Sending raw signed transactions to the network
Performing JSON-RPC calls directly to the node
Obtaining token metadata (ERC-721/ERC-1155)
Estimating gas for transactions
Retrieving current recommended gas fees

This specification enables client applications to interact programmatically with the Ethereum coinstack node and provides a structured, typed interface for blockchain data and transaction management.

Components

Schemas

The file defines multiple JSON schemas under [components.schemas](/projects/291/69205) which model the data structures used in requests and responses. These schemas define properties, types, required fields, and descriptions.

Key schemas include:

BaseInfo

Purpose: Describes basic information about the running coinstack.
Properties:
- network (string) - The blockchain network (e.g., "mainnet").
Example:
```
{
  "network": "mainnet"
}
```

TokenBalance

Purpose: Represents a token balance for an address, including metadata.
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 to preserve precision.
Required: All properties except id.

Account

Purpose: Contains detailed info about an EVM account.
Properties:
- balance (string) - Confirmed account balance.
- unconfirmedBalance (string) - Pending balance.
- pubkey (string) - Public address of the account.
- nonce (number) - Transaction nonce.
- tokens (array of TokenBalance) - List of tokens held by the account.

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: Provides detailed information about an Ethereum transaction.
Properties:
- txid (string) - Transaction hash.
- blockHash (string) - Hash of the block containing the transaction.
- blockHeight (number) - Block number.
- timestamp (number) - Unix timestamp of block time.
- from (string) - Sender address.
- to (string) - Recipient address.
- confirmations (number) - Number of confirmations.
- value (string) - Amount transferred.
- fee (string) - Transaction fee paid.
- gasLimit, gasUsed, gasPrice (string) - Gas parameters.
- status (number) - Transaction status (e.g., 1 for success).
- inputData (string, optional) - Input data for contract calls.
- tokenTransfers (array of TokenTransfer, optional) - Token transfer details.
- internalTxs (array of InternalTx, optional) - Internal transactions.

Example:

{
  "txid": "0x6850c6f3af68eb60a211af8f07f5b305375d0c94786b79a48371f5143953cb26",
  "blockHash": "0x969bda3f454330557492deacffb0ee8a7fd1d094cf884926d24c71ad11ed13bb",
  "blockHeight": 15624164,
  "timestamp": 1664275343,
  "status": 1,
  "from": "0xc730B028dA66EBB14f20e67c68DD809FBC49890D",
  "to": "0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF",
  "confirmations": 3911254,
  "value": "5384660932716527",
  "fee": "278408778879000",
  "gasLimit": "21000",
  "gasUsed": "21000",
  "gasPrice": "13257560899"
}

TokenMetadata

Purpose: Metadata information for ERC-721 and ERC-1155 tokens.
Properties:
- name (string) - Token name.
- description (string) - Description of the token.
- media (object) - Media asset associated with the token.
  - url (string) - URL of the media asset.
  - type (string enum: "image" or "video") - Media type.

Example:

{
  "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"
  }
}

GasFees

Purpose: Contains current recommended gas fees for Ethereum transactions.
Properties:
- baseFeePerGas (string) - Base fee per gas in wei.
- slow, average, fast (objects of type Fees) - Fee estimates for different confirmation speeds.
Usage: Clients can choose appropriate gas fees based on desired confirmation speed.

Paths (API Endpoints)

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

1. `GET /api/v1/info`

Description: Retrieves basic information about the running coinstack.
Response:
- 200 OK - Returns BaseInfo schema with network name.
Usage Example:
```
GET /api/v1/info
```

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

Description: Retrieves account details by public address.
Parameters:
- pubkey (string, path) - The Ethereum address.
Responses:
- 200 OK - Returns Account schema including balance, nonce, tokens.
- 400 Bad Request - Invalid input.
- 422 Validation Error - Request validation failed.
- 500 Internal Server Error - Server error.

Usage Example:

GET /api/v1/account/0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF

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

Description: Retrieves the transaction history for an address.
Parameters:
- pubkey (string, path) - Ethereum address.
- Optional query parameters for pagination and filtering:
  - cursor (string) - Cursor for pagination.
  - pageSize (number) - Number of transactions per page.
  - from (number) - Starting block number.
  - to (number) - Ending block number.
Responses:
- 200 OK - Returns TxHistory schema.
- 400, 422, 500 - Error responses.

Usage Example:

GET /api/v1/account/0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF/txs?pageSize=20&from=1000000

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

Description: Fetches detailed information about a specific transaction.
Parameters:
- txid (string, path) - Transaction hash.
Responses:
- 200 OK - Returns Tx schema.
- 400, 422, 500 - Error responses.

Usage Example:

GET /api/v1/tx/0x6850c6f3af68eb60a211af8f07f5b305375d0c94786b79a48371f5143953cb26

5. `POST /api/v1/send`

Description: Broadcasts a raw signed transaction hex to the blockchain node.
Request Body:
- hex (string) - Serialized raw transaction data.
Responses:
- 200 OK - Returns transaction ID string.
- 400, 422, 500 - Error responses.

Usage Example:

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

{
  "hex": "0xf86b808504a817c80082520894..."
}

6. `POST /api/v1/jsonrpc`

Description: Makes generic JSON-RPC requests (or batch requests) to the Ethereum node.
Request Body:
- Single or array of RPCRequest objects containing:
  - jsonrpc: "2.0"
  - id: request identifier
  - method: RPC method name
  - params: array of parameters
Responses:
- 200 OK - Returns corresponding RPCResponse or array of RPCResponse.

Usage Example:

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

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

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

Description: Retrieves metadata for a given ERC-721 or ERC-1155 token.
Query Parameters:
- contract (string) - Contract address of token.
- id (string) - Token identifier.
- type (string enum) - Token type (erc721 or erc1155).
Responses:
- 200 OK - Returns TokenMetadata schema.
- 422, 500 - Error responses.

Usage Example:

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

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

Description: Estimates the gas cost for a given transaction.
Request Body:
- Transaction data including data, from, to, and value.
Responses:
- 200 OK - Returns GasEstimate with gas limit.
- 422, 500 - Error responses.

Usage Example:

POST /api/v1/gas/estimate
Content-Type: application/json

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

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

Description: Retrieves current recommended gas fees for transactions, including EIP-1559 and legacy fee structures.
Responses:
- 200 OK - Returns GasFees schema.
- 500 - Internal server error.
Usage Notes:
- For EIP-1559 transactions, use maxFeePerGas and maxPriorityFeePerGas.
- For legacy transactions, use gasPrice.

Implementation Details

The API is designed using OpenAPI 3.0, enabling automatic generation of client SDKs, validation, and interactive documentation.
The schemas use strict typing with additionalProperties: false to enforce data shape integrity.
Pagination for transaction history uses a cursor-based approach with base64 encoded JSON cursors.
Supports both standard REST and JSON-RPC batch requests for flexible node interaction.
Token metadata supports both ERC-721 and ERC-1155 standards with media URL and type.
Gas fee recommendations include multiple speed tiers to optimize transaction costs.

Interaction with Other System Components

This API serves as the interface layer between clients (wallets, explorers, dApps) and the Ethereum node/coinstack backend.
It abstracts complex blockchain data structures and node RPC calls into user-friendly REST endpoints.
Token metadata retrieval likely integrates with off-chain metadata storage or IPFS gateways.
Gas estimation and fee recommendation endpoints interact with node mempool and fee market data for up-to-date information.
The send transaction endpoint allows clients to submit signed transactions, which the backend broadcasts to the Ethereum network.

Visual Diagram: API Structure Flowchart

flowchart TD
    A[API Root] --> B[/api/v1/info]
    A --> C[/api/v1/account/{pubkey}]
    C --> C1[/txs]
    A --> D[/api/v1/tx/{txid}]
    A --> E[/api/v1/send]
    A --> F[/api/v1/jsonrpc]
    A --> G[/api/v1/metadata/token]
    A --> H[/api/v1/gas/estimate]
    A --> I[/api/v1/gas/fees]

    subgraph AccountEndpoints
        C
        C1
    end

    subgraph TransactionEndpoints
        D
        E
    end

    subgraph GasEndpoints
        H
        I
    end

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333
    style C fill:#bbf,stroke:#333
    style C1 fill:#ccf,stroke:#333
    style D fill:#bbf,stroke:#333
    style E fill:#bbf,stroke:#333
    style F fill:#bbf,stroke:#333
    style G fill:#bbf,stroke:#333
    style H fill:#bbf,stroke:#333
    style I fill:#bbf,stroke:#333

Summary

The [swagger.json](/projects/291/68851) file fully describes a comprehensive REST and JSON-RPC API for interacting with an Ethereum coinstack. It provides detailed schemas and endpoints for account management, transaction querying, token metadata, gas estimation, and transaction broadcasting. The strict typing and rich metadata facilitate robust client implementation and integration with Ethereum blockchain infrastructure.

swagger.json

Overview

Components

Schemas

BaseInfo

TokenBalance

Account

Tx (Transaction)

TokenMetadata

GasFees

Paths (API 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

Interaction with Other System Components

Visual Diagram: API Structure Flowchart

Summary

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`