Add full monorepo: virtual-banker, backend, frontend, docs, scripts, deployment
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
defiQUG
430
backend/api/rest/swagger.yaml
Normal file
430
backend/api/rest/swagger.yaml
Normal file
@@ -0,0 +1,430 @@
|
||||
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"
|
||||
|
||||
Reference in New Issue
Block a user