431 lines
10 KiB
YAML
431 lines
10 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: SolaceScanScout API
|
|
description: |
|
|
Blockchain Explorer API for ChainID 138 with tiered access control.
|
|
|
|
## Authentication
|
|
|
|
Track 1 endpoints are public and require no authentication.
|
|
Track 2-4 endpoints require JWT authentication via wallet signature.
|
|
|
|
## Rate Limiting
|
|
|
|
- Track 1: 100 requests/minute per IP
|
|
- Track 2-4: Based on user tier and subscription
|
|
|
|
version: 1.0.0
|
|
contact:
|
|
name: API Support
|
|
email: support@d-bis.org
|
|
license:
|
|
name: MIT
|
|
url: https://opensource.org/licenses/MIT
|
|
|
|
servers:
|
|
- url: https://api.d-bis.org
|
|
description: Production server
|
|
- url: http://localhost:8080
|
|
description: Development server
|
|
|
|
tags:
|
|
- name: Health
|
|
description: Health check endpoints
|
|
- name: Blocks
|
|
description: Block-related endpoints
|
|
- name: Transactions
|
|
description: Transaction-related endpoints
|
|
- name: Addresses
|
|
description: Address-related endpoints
|
|
- name: Search
|
|
description: Unified search endpoints
|
|
- name: Track1
|
|
description: Public RPC gateway endpoints (no auth required)
|
|
- name: Track2
|
|
description: Indexed explorer endpoints (auth required)
|
|
- name: Track3
|
|
description: Analytics endpoints (Track 3+ required)
|
|
- name: Track4
|
|
description: Operator endpoints (Track 4 + IP whitelist)
|
|
|
|
paths:
|
|
/health:
|
|
get:
|
|
tags:
|
|
- Health
|
|
summary: Health check
|
|
description: Returns the health status of the API
|
|
operationId: getHealth
|
|
responses:
|
|
'200':
|
|
description: Service is healthy
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
example: ok
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
database:
|
|
type: string
|
|
example: connected
|
|
|
|
/api/v1/blocks:
|
|
get:
|
|
tags:
|
|
- Blocks
|
|
summary: List blocks
|
|
description: Returns a paginated list of blocks
|
|
operationId: listBlocks
|
|
parameters:
|
|
- name: limit
|
|
in: query
|
|
description: Number of blocks to return
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 100
|
|
default: 20
|
|
- name: page
|
|
in: query
|
|
description: Page number
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
default: 1
|
|
- name: chain_id
|
|
in: query
|
|
description: Chain ID filter
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
default: 138
|
|
responses:
|
|
'200':
|
|
description: List of blocks
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/BlockListResponse'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
|
|
/api/v1/blocks/{chain_id}/{number}:
|
|
get:
|
|
tags:
|
|
- Blocks
|
|
summary: Get block by number
|
|
description: Returns block details by chain ID and block number
|
|
operationId: getBlockByNumber
|
|
parameters:
|
|
- name: chain_id
|
|
in: path
|
|
required: true
|
|
description: Chain ID
|
|
schema:
|
|
type: integer
|
|
example: 138
|
|
- name: number
|
|
in: path
|
|
required: true
|
|
description: Block number
|
|
schema:
|
|
type: integer
|
|
example: 1000
|
|
responses:
|
|
'200':
|
|
description: Block details
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Block'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
|
|
/api/v1/transactions:
|
|
get:
|
|
tags:
|
|
- Transactions
|
|
summary: List transactions
|
|
description: Returns a paginated list of transactions
|
|
operationId: listTransactions
|
|
parameters:
|
|
- name: limit
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 20
|
|
- name: page
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 1
|
|
- name: chain_id
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 138
|
|
responses:
|
|
'200':
|
|
description: List of transactions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TransactionListResponse'
|
|
|
|
/api/v1/search:
|
|
get:
|
|
tags:
|
|
- Search
|
|
summary: Unified search
|
|
description: |
|
|
Searches for blocks, transactions, or addresses.
|
|
Automatically detects the type based on the query format.
|
|
operationId: search
|
|
parameters:
|
|
- name: q
|
|
in: query
|
|
required: true
|
|
description: Search query (block number, address, or transaction hash)
|
|
schema:
|
|
type: string
|
|
example: "0x1234567890abcdef"
|
|
responses:
|
|
'200':
|
|
description: Search results
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SearchResponse'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
|
|
/api/v1/track1/blocks/latest:
|
|
get:
|
|
tags:
|
|
- Track1
|
|
summary: Get latest blocks (Public)
|
|
description: Returns the latest blocks via RPC gateway. No authentication required.
|
|
operationId: getLatestBlocks
|
|
parameters:
|
|
- name: limit
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 10
|
|
maximum: 50
|
|
responses:
|
|
'200':
|
|
description: Latest blocks
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/BlockListResponse'
|
|
|
|
/api/v1/track2/search:
|
|
get:
|
|
tags:
|
|
- Track2
|
|
summary: Advanced search (Auth Required)
|
|
description: Advanced search with indexed data. Requires Track 2+ authentication.
|
|
operationId: track2Search
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- name: q
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Search results
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: JWT token obtained from /api/v1/auth/wallet
|
|
|
|
schemas:
|
|
Block:
|
|
type: object
|
|
properties:
|
|
chain_id:
|
|
type: integer
|
|
example: 138
|
|
number:
|
|
type: integer
|
|
example: 1000
|
|
hash:
|
|
type: string
|
|
example: "0x1234567890abcdef"
|
|
parent_hash:
|
|
type: string
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
miner:
|
|
type: string
|
|
transaction_count:
|
|
type: integer
|
|
gas_used:
|
|
type: integer
|
|
gas_limit:
|
|
type: integer
|
|
|
|
Transaction:
|
|
type: object
|
|
properties:
|
|
chain_id:
|
|
type: integer
|
|
hash:
|
|
type: string
|
|
block_number:
|
|
type: integer
|
|
from_address:
|
|
type: string
|
|
to_address:
|
|
type: string
|
|
value:
|
|
type: string
|
|
gas:
|
|
type: integer
|
|
gas_price:
|
|
type: string
|
|
status:
|
|
type: string
|
|
enum: [success, failed]
|
|
|
|
BlockListResponse:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Block'
|
|
pagination:
|
|
$ref: '#/components/schemas/Pagination'
|
|
|
|
TransactionListResponse:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Transaction'
|
|
pagination:
|
|
$ref: '#/components/schemas/Pagination'
|
|
|
|
Pagination:
|
|
type: object
|
|
properties:
|
|
page:
|
|
type: integer
|
|
limit:
|
|
type: integer
|
|
total:
|
|
type: integer
|
|
total_pages:
|
|
type: integer
|
|
|
|
SearchResponse:
|
|
type: object
|
|
properties:
|
|
query:
|
|
type: string
|
|
results:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [block, transaction, address]
|
|
data:
|
|
type: object
|
|
|
|
Error:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: string
|
|
message:
|
|
type: string
|
|
|
|
responses:
|
|
BadRequest:
|
|
description: Bad request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
error:
|
|
code: "bad_request"
|
|
message: "Invalid request parameters"
|
|
|
|
Unauthorized:
|
|
description: Unauthorized - Authentication required
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
error:
|
|
code: "unauthorized"
|
|
message: "Authentication required"
|
|
|
|
Forbidden:
|
|
description: Forbidden - Insufficient permissions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
error:
|
|
code: "forbidden"
|
|
message: "Insufficient permissions. Track 2+ required."
|
|
|
|
NotFound:
|
|
description: Resource not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
error:
|
|
code: "not_found"
|
|
message: "Resource not found"
|
|
|
|
InternalServerError:
|
|
description: Internal server error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
error:
|
|
code: "internal_error"
|
|
message: "An internal error occurred"
|
|
|