swagger.json

Overview

This file is an OpenAPI 3.0 specification document describing the RESTful HTTP API endpoints, request/response schemas, and metadata for the [@shapeshiftoss/base-api](/projects/291/68900) version 10.0.0. The API provides functionality primarily for interacting with an EVM-compatible blockchain coinstack, focusing on account information, transaction management, gas fee estimation, and token metadata retrieval.

The specification standardizes how clients can query blockchain data (accounts, transactions, token balances), send raw transactions, perform JSON-RPC calls, and fetch gas fee estimates. It encapsulates schema definitions for request and response payloads, error handling, and the structure of various blockchain entities such as accounts, tokens, and transactions.

This file serves as both a machine-readable API contract for client-server communication and human-readable documentation for developers integrating with this blockchain API.

Detailed Components

Schemas

Schemas define the structure of data objects used in requests or responses.

BaseInfo

Description: Basic information about the running coinstack.
Properties:
- network (string, required): The name of the blockchain network (e.g., "mainnet").
Usage Example:
```
{
  "network": "mainnet"
}
```

TokenBalance

Description: Information about a token including the 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 identifier.
- balance (string, required): Token balance as a string to handle large numbers.

Example:

{
  "contract": "0x123...",
  "decimals": 18,
  "name": "ExampleToken",
  "symbol": "EXT",
  "type": "ERC20",
  "balance": "1000000000000000000"
}

Account

Description: Information about an EVM account.
Properties:
- balance (string, required): Confirmed balance.
- unconfirmedBalance (string, required): Unconfirmed balance.
- pubkey (string, required): Public address of the account.
- nonce (number, required): Transaction nonce.
- tokens (array of TokenBalance, required): List of token balances.

Example:

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

BadRequestError

Description: Response schema for HTTP 400 Bad Request.
Properties:
- error (string, required): Error message.

ValidationError

Description: Response schema for HTTP 422 Validation Error.
Properties:
- message (string, required): Fixed value "Validation failed".
- details (object, required): Additional error details.

InternalServerError

Description: Response schema for HTTP 500 Internal Server Error.
Properties:
- message (string, required): Error message.

TokenTransfer

Description: Contains token transfer details.
Properties:
- contract, decimals, name, symbol, type (similar to TokenBalance).
- id (string, optional): NFT or multi-token id.
- from (string, required): Sender address.
- to (string, required): Recipient address.
- value (string, required): Transfer amount.

InternalTx

Description: EVM internal transaction details (calls within contracts).
Properties:
- from, to (string, required): Addresses involved.
- value (string, required): Value transferred.

Tx

Description: EVM transaction details.
Properties:
- txid (string, required): Transaction hash.
- blockHash (string, optional): Block hash.
- blockHeight (number, required): Block number.
- timestamp (number, required): Unix timestamp.
- from, to (string, required): Addresses.
- confirmations (number, required): Number of confirmations.
- value (string, required): Amount transferred.
- fee (string, required): Transaction fee.
- gasLimit, gasUsed, gasPrice (string, required): Gas parameters.
- status (number, required): Transaction status (e.g., 1 for success).
- inputData (string, optional): Input data payload.
- tokenTransfers (array of TokenTransfer, optional): Token transfers within the transaction.
- internalTxs (array of InternalTx, optional): Internal transactions.

BaseTxHistory_Tx_

Description: Paginated transaction history.
Properties:
- cursor (string, optional): Cursor for pagination.
- pubkey (string, required): Account address.
- txs (array of Tx, required): List of transactions.

TxHistory

Alias for BaseTxHistory_Tx_.
Contains info about EVM transaction history.

SendTxBody

Description: Payload to send raw serialized transaction.
Properties:
- hex (string, required): Serialized transaction hex string.

RPCRequest

Description: JSON-RPC 2.0 request format.
Properties:
- jsonrpc (string, required): Must be "2.0".
- id (string or number, required): Request identifier.
- method (string, required): JSON-RPC method name.
- params (array, optional): Parameters for the method.

RPCResponse

Description: JSON-RPC 2.0 response format.
Properties:
- jsonrpc (string, required): Must be "2.0".
- id (string or number, required): Corresponds to request id.
- result (any, optional): Result value.
- error (object, optional): Error object with code, message, and optional data.

TokenMetadata

Description: Metadata for tokens (ERC-721/ERC-1155).
Properties:
- name (string, required): Token name.
- description (string, required): Token description.
- media (object, required): Media data for token.
  - Properties:
    - type (string, enum: image, video): Media type.
    - url (string, required): URL to the media resource.

TokenType

Description: Supported token types.
Enum: erc721, erc1155.

BaseGasEstimate

Description: Estimated gas cost for transactions on L1 and L2.
Properties:
- gasLimit (string, required): Gas limit estimate.
- l1GasLimit (string, required): L1 gas limit estimate.

EstimateGasBody

Description: Data required to estimate gas cost.
Properties:
- data (string, required): Transaction data.
- from (string, required): Sender address.
- to (string, required): Recipient address.
- value (string, required): Value to send.

Fees

Description: Legacy and EIP-1559 fee parameters.
Properties:
- gasPrice (string, required): Legacy gas price.
- maxFeePerGas (string, optional): Max fee per gas (EIP-1559).
- maxPriorityFeePerGas (string, optional): Max priority fee per gas (EIP-1559).

BaseGasFees

Description: Current recommended gas fees on L1 and L2.
Properties:
- baseFeePerGas (string, optional): Base fee per gas.
- slow, average, fast (all required, Fees): Fee tiers.
- l1GasPrice (string, required): L1 gas price.

API Paths and Operations

1. Get Info

Endpoint: GET /api/v1/info
OperationId: GetInfo
Description: Retrieves basic information about the running coinstack.
Response 200: Returns BaseInfo schema.
Example:
```
{
  "network": "mainnet"
}
```
Usage: Fetch network type to confirm environment.

2. Get Account Details

Endpoint: GET /api/v1/account/{pubkey}
OperationId: GetAccount
Parameters:
- pubkey (path, string, required): Account address.
Description: Fetch detailed information about an EVM account including balance, nonce, and tokens.
Responses:
- 200: Account schema with token balances.
- 400: BadRequestError
- 422: ValidationError
- 500: InternalServerError

Example response snippet:

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

Use case: Wallet apps to show account balances and tokens.

3. Get Transaction History

Endpoint: GET /api/v1/account/{pubkey}/txs
OperationId: GetTxHistory
Parameters:
- pubkey (path, string, required): Account address.
- cursor (query, string, optional): Pagination cursor.
- pageSize (query, number, optional, default=10): Number of transactions per page.
- from (query, number, optional): Start block number.
- to (query, number, optional): End block number.
Description: Retrieve paginated transaction history of an account.
Responses:
- 200: TxHistory schema.
- 400, 422, 500: Error schemas.

Example response snippet:

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

4. Get Transaction Details

Endpoint: GET /api/v1/tx/{txid}
OperationId: GetTransaction
Parameters:
- txid (path, string, required): Transaction hash.
Description: Fetch details of a specific transaction.
Responses:
- 200: Tx schema.
- 400, 422, 500: Error schemas.

5. Send Transaction

Endpoint: POST /api/v1/send
OperationId: SendTx
Request Body: SendTxBody schema:
- hex (string): Serialized raw transaction hex string.
Description: Broadcast a raw transaction to the node.
Responses:
- 200: Transaction ID string.
- 400, 422, 500: Error schemas.

Example Request:

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

6. JSON-RPC Request Proxy

Endpoint: POST /api/v1/jsonrpc
OperationId: DoRpcRequest
Request Body: RPCRequest or array of RPCRequest (batch).
Description: Make JSON-RPC calls to the underlying node (e.g., eth_blockNumber).
Responses:
- 200: RPCResponse or array of RPCResponse.

Example Request:

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

Example Response:

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

7. Get Token Metadata

Endpoint: GET /api/v1/metadata/token
OperationId: GetTokenMetadata
Parameters:
- contract (query, string, required): Token contract address.
- id (query, string, required): Token identifier.
- type (query, TokenType enum, required): Token type (erc721 or erc1155).
Description: Retrieve metadata about a token, including media URL and description.
Responses:
- 200: TokenMetadata schema.
- 422, 500: Error schemas.

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. Estimate Gas Cost

Endpoint: POST /api/v1/gas/estimate
OperationId: EstimateGas
Request Body: EstimateGasBody schema with transaction data.
Description: Estimate the gas cost of a transaction including on L1 and L2.
Responses:
- 200: BaseGasEstimate schema.
- 422, 500: Error schemas.

Example Request:

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

Example Response:

{
  "gasLimit": "21000",
  "l1GasLimit": "1664"
}

9. Get Current Gas Fees

Endpoint: GET /api/v1/gas/fees
OperationId: GetGasFees
Description: Retrieve current recommended gas fees including legacy and EIP-1559 parameters.
Responses:
- 200: BaseGasFees schema.
- 500: InternalServerError.

Example Response:

{
  "l1GasPrice": "5349789102",
  "baseFeePerGas": "51497198",
  "slow": {
    "gasPrice": "51815704",
    "maxFeePerGas": "51947082",
    "maxPriorityFeePerGas": "428650"
  },
  "average": {
    "gasPrice": "53149928",
    "maxFeePerGas": "52728076",
    "maxPriorityFeePerGas": "1209644"
  },
  "fast": {
    "gasPrice": "105353129",
    "maxFeePerGas": "145357641",
    "maxPriorityFeePerGas": "93839209"
  }
}

Important Implementation Details

The API adheres strictly to OpenAPI 3.0 specification for formalizing the REST endpoints and schemas.
Uses precise data types and formats for blockchain-specific data such as hex strings, large numbers (as strings), and timestamps.
Supports both single and batch JSON-RPC requests for node interaction.
Pagination in transaction history uses cursors encoded as base64-encoded JSON objects.