swagger.json

Overview

This file is an **OpenAPI 3.0** specification document for the [@shapeshiftoss/optimism-api](/projects/291/68947) version `10.0.0`. It defines a RESTful API that provides access to various functionalities related to the **Optimism** Ethereum Layer 2 scaling solution. The API exposes endpoints to:

Retrieve blockchain and network information.
Query account balances and transaction histories.
Fetch transaction details.
Submit raw transactions.
Perform JSON-RPC calls on the underlying node.
Obtain token metadata (e.g., ERC-721/ERC-1155 NFTs).
Estimate gas costs and fetch current gas fees.

This specification serves as a contract between the API provider and consumers, enabling automatic generation of client SDKs, server stubs, and comprehensive documentation.

Detailed Components Documentation

Components Schemas

The file includes detailed JSON Schemas describing data structures used in requests and responses.

1. BaseInfo

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

2. TokenBalance

Description: Information about a token 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): Token ID for NFTs or multi-tokens.
- balance (string, required): Token balance as string to avoid precision loss.

Example:

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

3. Account

Description: Contains information about an EVM account.
Properties:
- balance (string, required): Confirmed balance.
- unconfirmedBalance (string, required): Unconfirmed balance.
- pubkey (string, required): Account public key (address).
- nonce (number, required): Transaction count for the account.
- tokens (array of TokenBalance, required): List of tokens owned.

Example:

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

4. Tx (Transaction)

Description: Details about an EVM transaction.
Properties:
- txid (string, required): Transaction hash.
- blockHash (string, optional): Hash of the block containing the transaction.
- blockHeight (number, required): Block number.
- timestamp (number, required): Unix timestamp of the block.
- from (string, required): Sender address.
- to (string, required): Recipient address.
- confirmations (number, required): Number of confirmations.
- value (string, required): Amount transferred (in wei).
- fee (string, required): Transaction fee paid.
- gasLimit (string, required): Gas limit set for the transaction.
- gasUsed (string, optional): Gas used by the transaction.
- gasPrice (string, required): Gas price in wei.
- status (number, required): Status code (e.g., 1 = success).
- inputData (string, optional): Input data (hex-encoded).
- tokenTransfers (array of TokenTransfer, optional): Token transfer details.
- internalTxs (array of InternalTx, optional): Internal transaction details.

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

5. TokenTransfer

Description: Details about token transfer within a transaction.
Properties:
- contract, decimals, name, symbol, type, id (like TokenBalance).
- from (string, required): Sender address.
- to (string, required): Recipient address.
- value (string, required): Amount transferred.
Note: Useful for tracking ERC-20, ERC-721, or ERC-1155 token movements.

6. InternalTx

Description: Details about internal (contract-to-contract) transactions.
Properties:
- from (string, required): Sender address.
- to (string, required): Recipient address.
- value (string, required): Value transferred.

7. TxHistory / BaseTxHistory_Tx_

Description: Paginated transaction history for an account.
Properties:
- pubkey (string, required): Account address.
- txs (array of Tx, required): Transactions.
- cursor (string, optional): Pagination cursor for fetching next page.

8. SendTxBody

Description: Request body schema for submitting a raw transaction.
Properties:
- hex (string, required): Serialized raw transaction in hex.

9. RPCRequest / RPCResponse

Description: JSON-RPC 2.0 request and response formats.
RPCRequest Properties:
- jsonrpc (string, required): Must be "2.0".
- id (string or number, required): Request identifier.
- method (string, required): RPC method name.
- params (array, optional): Method parameters.
RPCResponse Properties:
- jsonrpc (string, required): "2.0".
- id (string or number, required): Matches request id.
- result (any, optional): Result of the call.
- error (object, optional): Error details if call failed.

10. TokenMetadata

Description: Metadata for ERC-721/ERC-1155 tokens.
Properties:
- name (string, required): Token name.
- description (string, required): Description of token.
- media (object, required):
  - url (string, required): Media URL.
  - type (string, enum: "image" or "video", optional): Media type.

11. EstimateGasBody & OptimismGasEstimate

EstimateGasBody: Request data for estimating gas.
- data (string, required): Transaction data.
- from (string, required): Sender address.
- to (string, required): Recipient address.
- value (string, required): Value in wei.
OptimismGasEstimate: Response format for estimated gas.
- gasLimit (string, required): Estimated gas limit on L2.
- l1GasLimit (string, required): Estimated gas limit on L1.

12. Fees & OptimismGasFees

Fees: Fee structure for legacy or EIP-1559 transactions.
- gasPrice (string, required)
- maxFeePerGas (string, optional)
- maxPriorityFeePerGas (string, optional)
OptimismGasFees: Recommended gas fees for transactions on L1 and L2.
- baseFeePerGas (string, optional): Base gas fee.
- slow, average, fast (Fees, required): Different fee tiers.
- l1GasPrice (string, required): Current L1 gas price.

13. Error Responses

BadRequestError: 400 Bad Request, includes an error string.
ValidationError: 422 Validation Error, includes:
- message (string, "Validation failed")
- details (object): Additional error details.
InternalServerError: 500 Internal Server Error, includes a message string.

API Endpoints

All endpoints are prefixed with `/api/v1`.

1. GET `/info`

OperationId: GetInfo
Description: Returns basic info about the running coinstack network.
Response: BaseInfo object.
Example Response:
```
{
  "network": "mainnet"
}
```

2. GET `/account/{pubkey}`

OperationId: GetAccount
Description: Returns account details including balances and tokens.
Path Parameter:
- pubkey (string, required): Account address.
Responses:
- 200: Account object.
- 400, 422, 500: Error schemas.
Example Response:
See Account example above.

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

OperationId: GetTxHistory
Description: Returns paginated transaction history for the account.
Path Parameter:
- pubkey (string, required): Account address.
Query Parameters:
- cursor (string, optional): Pagination cursor.
- pageSize (number, optional, default 10): Number of transactions per page.
- from (number, optional): Starting block number.
- to (number, optional): Ending block number.
Response: TxHistory object.
Example Response:
See Tx example above.

4. GET `/tx/{txid}`

OperationId: GetTransaction
Description: Returns details for a specific transaction by hash.
Path Parameter:
- txid (string, required): Transaction hash.
Response: Tx object.

5. POST `/send`

OperationId: SendTx
Description: Broadcasts a serialized raw transaction to the node.
Request Body: SendTxBody (raw hex string).
Response: Transaction ID string on success.

6. POST `/jsonrpc`

OperationId: DoRpcRequest
Description: Forwards a JSON-RPC request or batch to the node.
Request Body: Single or array of RPCRequest.
Response: Single or array of RPCResponse.

7. GET `/metadata/token`

OperationId: GetTokenMetadata
Description: Retrieves metadata for a token (ERC-721/ERC-1155).
Query Parameters:
- contract (string, required): Contract address.
- id (string, required): Token ID.
- type (TokenType, required): Token type enum ("erc721" or "erc1155").
Response: TokenMetadata.

8. POST `/gas/estimate`

OperationId: EstimateGas
Description: Estimates gas cost for a transaction.
Request Body: EstimateGasBody.
Response: OptimismGasEstimate.

9. GET `/gas/fees`

OperationId: GetGasFees
Description: Gets current recommended gas fees for transactions.
Response: OptimismGasFees.

Important Implementation Details and Algorithms

Pagination: The /account/{pubkey}/txs endpoint supports pagination via a cursor query parameter, which is a base64 encoded JSON object containing a page property. This allows clients to fetch transaction history pages efficiently.
Token Support: The API supports standard ERC-20 tokens as well as NFT standards ERC-721 and ERC-1155, including metadata retrieval for tokens.
Gas Estimation: The gas estimation endpoint provides layered estimates for both Layer 1 and Layer 2 gas costs, reflecting Optimism's rollup architecture.
JSON-RPC Proxy: The /jsonrpc endpoint allows clients to send arbitrary JSON-RPC requests directly to the underlying Ethereum node, supporting both single and batch requests.
Error Handling: The API uses standard HTTP status codes with well-defined JSON schemas for 400 Bad Request, 422 Validation Error, and 500 Internal Server Error responses, enabling clients to handle errors gracefully.

Integration and Interactions

This API serves as the interface layer between client applications (such as wallets, explorers, or DApps) and the Optimism blockchain node or coinstack.
It abstracts complex blockchain data structures into user-friendly JSON schemas, providing account balances, transaction histories, token details, and transaction broadcast capabilities.
The API integrates with token metadata services to enrich NFT information.
The gas estimation and fee endpoints interact with Optimism’s Layer 1 and Layer 2 systems to provide accurate transaction cost predictions.
The JSON-RPC forwarding endpoint enables advanced users or applications to perform custom queries or commands against the underlying Ethereum node while still using this API as a proxy.

Usage Examples

Example: 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"
    }
  ]
}

Example: Send Raw Transaction

**Request:**

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

{
  "hex": "0xf86b808504a817c80082520894ad6d458402f60fd3bd25163575031acdce07538d880de0b6b3a76400008025a0e9d..."
}

**Response:**

"0x123abc..."

Visual Diagram of File Structure

This file is primarily a **specification document** describing schemas and API paths. It does not define classes or functions but organizes components (schemas) and endpoints.

The diagram below illustrates the structural relationship between **schemas** and **API paths**, highlighting request/response flow.

flowchart TD
    subgraph Schemas
        BaseInfo["BaseInfo"]
        Account["Account"]
        TokenBalance["TokenBalance"]
        Tx["Tx"]
        TokenTransfer["TokenTransfer"]
        InternalTx["InternalTx"]
        TxHistory["TxHistory"]
        SendTxBody["SendTxBody"]
        RPCRequest["RPCRequest"]
        RPCResponse["RPCResponse"]
        TokenMetadata["TokenMetadata"]
        EstimateGasBody["EstimateGasBody"]
        OptimismGasEstimate["OptimismGasEstimate"]
        Fees["Fees"]
        OptimismGasFees["OptimismGasFees"]
        Errors["Error Schemas"]
    end

    subgraph API_Paths
        Info["GET /info"]
        GetAccount["GET /account/{pubkey}"]
        GetTxHistory["GET /account/{pubkey}/txs"]
        GetTx["GET /tx/{txid}"]
        SendTx["POST /send"]
        JsonRpc["POST /jsonrpc"]
        TokenMeta["GET /metadata/token"]
        GasEstimate["POST /gas/estimate"]
        GasFees["GET /gas/fees"]
    end

    %% Relationships
    Info -->|response| BaseInfo
    GetAccount -->|response| Account
    Account --> TokenBalance
    GetTxHistory -->|response| TxHistory
    TxHistory --> Tx
    Tx --> TokenTransfer
    Tx --> InternalTx
    GetTx -->|response| Tx
    SendTx -->|request| SendTxBody
    SendTx -->|response| "string (txid)"
    JsonRpc -->|request| RPCRequest
    JsonRpc -->|response| RPCResponse
    TokenMeta -->|response| TokenMetadata
    GasEstimate -->|request| EstimateGasBody
    GasEstimate -->|response| OptimismGasEstimate
    GasFees -->|response| OptimismGasFees

    %%

swagger.json

Overview

Detailed Components Documentation

Components Schemas

1. BaseInfo

2. TokenBalance

3. Account

4. Tx (Transaction)

5. TokenTransfer

6. InternalTx

7. TxHistory / BaseTxHistory_Tx_

8. SendTxBody

9. RPCRequest / RPCResponse

10. TokenMetadata

11. EstimateGasBody & OptimismGasEstimate

12. Fees & OptimismGasFees

13. Error Responses

API Endpoints

1. GET /info

2. GET /account/{pubkey}

3. GET /account/{pubkey}/txs

4. GET /tx/{txid}

5. POST /send

6. POST /jsonrpc

7. GET /metadata/token

8. POST /gas/estimate

9. GET /gas/fees

Important Implementation Details and Algorithms

Integration and Interactions

Usage Examples

Example: Get Account Details

Example: Send Raw Transaction

Visual Diagram of File Structure

1. GET `/info`

2. GET `/account/{pubkey}`

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

4. GET `/tx/{txid}`

5. POST `/send`

6. POST `/jsonrpc`

7. GET `/metadata/token`

8. POST `/gas/estimate`

9. GET `/gas/fees`