swagger.json

Overview

The [swagger.json](/projects/291/68851) file is an OpenAPI 3.0 specification document that defines the RESTful API interface for the [@shapeshiftoss/dogecoin-api](/projects/291/69281) service (version 10.0.0). This API provides endpoints to interact with a Dogecoin coinstack, allowing clients to query blockchain data such as account details, transaction history, unspent transaction outputs (UTXOs), transaction details, broadcast raw transactions, and retrieve current network fee recommendations.

The file serves as a contract between API providers and consumers, detailing available paths, HTTP methods, request parameters, response schemas, error handling, and server information. It is primarily used for API documentation, client SDK generation, and automated testing.

Components

The [components](/projects/291/69205) section contains reusable schema definitions (data models), error response formats, and (though empty here) security schemes. These schemas describe the shape and constraints of request and response payloads.

Schemas

Below are key data schemas defined in [swagger.json](/projects/291/68851):

BaseInfo

• Description: Basic info about the running coinstack.

• Properties:

  • network (string) - Network name (e.g., mainnet, testnet).

• Required: network

• Example Usage: Returned by the /api/v1/info endpoint.

Address

• Description: Information about an address linked to an extended public key.

• Properties:

  • balance (string) - Balance of the address.

  • pubkey (string) - Public key associated with the address.

• Required: balance, pubkey

Account

• Description: Contains info about an account (address or extended public key).

• Properties:

  • balance (string) - Confirmed balance.

  • unconfirmedBalance (string) - Unconfirmed balance.

  • pubkey (string) - The public key.

  • addresses (array of Address) - List of associated addresses.

  • nextReceiveAddressIndex (number) - Next unused receive address index.

  • nextChangeAddressIndex (number) - Next unused change address index.

• Required: balance, unconfirmedBalance, pubkey

Vin (Transaction Input)

• Description: Details about a transaction input.

• Properties:

  • txid (string) - Transaction ID of the previous output.

  • vout (string) - Output index.

  • sequence (number) - Sequence number.

  • coinbase (string) - Coinbase data if applicable.

  • scriptSig (object) - Script signature details including hex.

  • addresses (array of strings) - Addresses involved.

  • value (string) - Value of the input.

• Additional properties disallowed.

Vout (Transaction Output)

• Description: Details about a transaction output.

• Properties:

  • value (string) - Output value.

  • n (number) - Output index.

  • opReturn (string) - OP_RETURN data if present.

  • scriptPubKey (object) - Script public key details including hex.

  • addresses (array of strings) - Addresses receiving the output.

• Required: value, n, scriptPubKey

Tx (Transaction)

• Description: Contains transaction details.

• Properties:

  • txid (string) - Transaction ID.

  • blockHash (string) - Block hash containing the transaction.

  • blockHeight (number) - Height of the block.

  • timestamp (number) - Unix timestamp of the transaction.

  • vin (array of Vin) - Transaction inputs.

  • vout (array of Vout) - Transaction outputs.

  • confirmations (number) - Number of confirmations.

  • value (string) - Total transaction value.

  • fee (string) - Transaction fee.

  • hex (string) - Raw transaction hex.

• Required: All except blockHash (optional).

BaseTxHistory_Tx_

• Description: Paginated transaction history for an account.

• Properties:

  • cursor (string) - Pagination cursor.

  • pubkey (string) - Public key queried.

  • txs (array of Tx) - Transactions.

• Required: pubkey, txs

TxHistory

• Alias to BaseTxHistory_Tx_.

• Used in endpoints returning transaction history.

Utxo (Unspent Transaction Output)

• Description: Details about a UTXO.

• Properties:

  • txid (string) - Transaction ID.

  • vout (number) - Output index.

  • value (string) - Value of UTXO.

  • height (number) - Block height.

  • confirmations (number) - Confirmations count.

  • address (string) - Associated address.

  • path (string) - Derivation path.

  • locktime (number) - Lock time.

  • coinbase (boolean) - Coinbase indicator.

• Required: txid, vout, value, confirmations

RawTx

• Description: Detailed raw transaction data as returned from the node.

• Properties: Includes all standard Bitcoin/Dogecoin raw transaction fields such as txid, version, vin, vout, hex, confirmations, time, etc.

• Required: Comprehensive list of transaction fields.

• Used for: /api/v1/tx/{txid}/raw endpoint.

SendTxBody

• Description: Payload to send a raw transaction to the network.

• Properties:

  • hex (string) - Serialized raw transaction hex.

• Required: hex

NetworkFee

• Description: Network fee info for different confirmation speeds.

• Properties:

  • satsPerKiloByte (number) - Fee rate in satoshis per KB.

  • blocksUntilConfirmation (number) - Estimated blocks until confirmation.

• Required: Both properties.

NetworkFees

• Description: Recommended network fees at different speeds.

• Properties:

  • fast (NetworkFee) - Fast confirmation fee.

  • average (NetworkFee) - Average confirmation fee.

  • slow (NetworkFee) - Slow confirmation fee.

API Paths and Operations

The API exposes the following primary endpoints under `/api/v1`:

1. GET /api/v1/info

• OperationId: GetInfo

• Description: Get basic info about the running Dogecoin coinstack.

• Response:

  • 200 OK - Returns BaseInfo object.

• Usage example:

GET /api/v1/info HTTP/1.1
Host: example.com

Response:
{
  "network": "mainnet"
}

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

• OperationId: GetAccount

• Description: Get account details by Dogecoin address or extended public key.

• Parameters:

  • pubkey (string, path, required) - Address or extended public key.

• Responses:

  • 200 OK - Returns Account object.

  • 400 Bad Request - Returns BadRequestError.

  • 422 Validation Error - Returns ValidationError.

  • 500 Internal Server Error - Returns InternalServerError.

• Usage example:

GET /api/v1/account/abc123pubkey HTTP/1.1

Response:
{
  "balance": "1000000",
  "unconfirmedBalance": "50000",
  "pubkey": "abc123pubkey",
  "addresses": [...],
  "nextReceiveAddressIndex": 5,
  "nextChangeAddressIndex": 2
}

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

• OperationId: GetTxHistory

• Description: Retrieve transaction history for an account.

• Parameters:

  • pubkey (string, path, required)

  • cursor (string, query, optional) - Pagination cursor.

  • pageSize (number, query, optional, default 10) - Number of transactions per page.

• Responses: Same as GetAccount, with 200 OK returning a TxHistory object.

4. GET /api/v1/account/{pubkey}/utxos

• OperationId: GetUtxos

• Description: Retrieve all unspent transaction outputs (UTXOs) for an account.

• Parameters: pubkey (string, path, required)

• Responses: Same error responses as above; 200 OK returns an array of Utxo objects.

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

• OperationId: GetTransaction

• Description: Retrieve transaction details by transaction ID.

• Parameters: txid (string, path, required)

• Responses: Returns Tx object or error responses.

6. GET /api/v1/tx/{txid}/raw

• OperationId: GetRawTransaction

• Description: Retrieve raw transaction details directly from the Dogecoin node.

• Parameters: txid (string, path, required)

• Responses: Returns RawTx object or error responses.

7. POST /api/v1/send

• OperationId: SendTx

• Description: Broadcast a serialized raw transaction hex to the network.

• Request Body:

  • JSON containing hex (string) — serialized raw transaction.

• Responses:

  • 200 OK - Returns transaction ID string.

  • Error responses as described above.

• Usage example:

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

{
  "hex": "0100000001abcdef..."
}

Response:
"txid1234567890"

8. GET /api/v1/fees

• OperationId: GetNetworkFees

• Description: Get current recommended network fees for transactions.

• Response:

  • 200 OK - Returns NetworkFees object with fast, average, and slow fee estimates.

Error Schemas

• BadRequestError: { "error": string } — for 400 Bad Request.

• ValidationError: { "message": "Validation failed", "details": object } — for 422 errors.

• InternalServerError: { "message": string } — for 500 errors.

Important Implementation Details

• Strict Schemas: All schemas disallow additional properties, ensuring strict validation.

• Pagination: Transaction history supports cursor-based pagination.

• Raw and Parsed Transactions: The API provides both parsed (Tx) and raw (RawTx) transaction formats.

• Fee Recommendations: Fees are categorized by confirmation speed (fast, average, slow) with sats/KB and estimated blocks to confirmation.

• No Security Schemes Defined: The API definition currently lacks security schemes (authentication/authorization), implying open or externally managed access control.

Interaction With Other System Components

• This OpenAPI spec defines the contract for the Dogecoin API backend service.

• Backend implementation will parse requests according to these schemas and paths, perform blockchain queries or commands, and respond with conforming JSON.

• Client applications, SDKs, or API gateways use this spec for generating clients, validating requests, or documenting the API.

• The spec references Dogecoin coinstack internals (UTXOs, transactions, addresses) and node-level raw transaction data.

• The sending transaction endpoint integrates with the network broadcast layer.

Visual Diagram: API Structure Flowchart

flowchart TD
    A[API Root] --> B[GET /api/v1/info]
    A --> C[GET /api/v1/account/{pubkey}]
    A --> D[GET /api/v1/account/{pubkey}/txs]
    A --> E[GET /api/v1/account/{pubkey}/utxos]
    A --> F[GET /api/v1/tx/{txid}]
    A --> G[GET /api/v1/tx/{txid}/raw]
    A --> H[POST /api/v1/send]
    A --> I[GET /api/v1/fees]

    C --> |Returns| Account
    D --> |Returns| TxHistory
    E --> |Returns| Utxo[]
    F --> |Returns| Tx
    G --> |Returns| RawTx
    H --> |Request| SendTxBody
    H --> |Returns| txid (string)
    I --> |Returns| NetworkFees
    B --> |Returns| BaseInfo

Summary

This [swagger.json](/projects/291/68851) file comprehensively defines the Dogecoin API for querying blockchain data, managing accounts, retrieving transactions and UTXOs, sending transactions, and fetching fee recommendations. It uses strict and detailed JSON schemas to describe data structures and robustly defines various HTTP endpoints with clear operation IDs and error handling.

This specification is essential for developers and integrators to understand, consume, and implement the Dogecoin API consistently, ensuring reliable and predictable interactions with the Dogecoin coinstack service.