openapi: 3.0.3
info:
title: Monaco Protocol API
description: REST API for the Monaco Protocol hybrid CLOB exchange.
version: 1.0.0
servers:
- url: https://develop.apimonaco.xyz
description: Development server
- url: https://staging.apimonaco.xyz
description: Staging server (Testnet)
paths:
/api/v1/accounts/balances:
get:
tags:
- AccountsService
- Accounts
summary: Get user balances
description: |-
Get user balances.
Get the current user's token balances with pagination support. Returns
available, locked, and total balance for each token.
operationId: get_user_balances
parameters:
- name: page
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 10000
description: Page number (1-indexed)
- name: page_size
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 100
default: 20
description: Items per page (max 100)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetBalancesResponse'
'400':
description: Invalid request
'401':
description: Authentication required
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/accounts/balances/{asset_id}:
get:
tags:
- AccountsService
- Accounts
summary: Get user balance by asset
description: |-
Get user balance by asset.
Get the current user's balance for a specific asset. Returns available,
locked, and total balance. If no balance exists for a valid asset, returns
zero balances. If the asset ID is invalid or not found, returns 404.
operationId: get_user_balance_by_asset
parameters:
- name: asset_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetBalanceByAssetResponse'
'400':
description: Invalid request
'401':
description: Authentication required
'404':
description: Asset not found
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/accounts/me:
get:
tags:
- AccountsService
- Accounts
summary: Get user profile
description: |-
Get user profile.
Get the current user's profile with token balances, recent movements,
and recent orders. Use `source` to control data source: `hot_storage`
(fast, real-time), `cold_storage` (historical), or `both` (hybrid).
operationId: get_user_profile
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetProfileResponse'
'400':
description: Invalid request
'401':
description: Authentication required
'404':
description: User not found
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/accounts/me/portfolio:
get:
tags:
- AccountsService
- Accounts
summary: Get portfolio stats
description: |-
Get portfolio stats.
Get aggregate portfolio statistics for the authenticated user,
scoped by time period. Includes volume, PnL, fees, equity, and
win/loss metrics.
operationId: get_portfolio_stats
parameters:
- name: period
in: query
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetPortfolioStatsResponse'
'400':
description: Invalid period parameter
'401':
description: Authentication required
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/accounts/me/portfolio/chart:
get:
tags:
- AccountsService
- Accounts
summary: Get portfolio chart time series
description: |-
Get portfolio chart time series.
Get bucketed time series data for portfolio charts. Supports volume
and PnL metrics with configurable time periods and automatic bucket sizing.
operationId: get_portfolio_chart
parameters:
- name: period
in: query
schema:
type: string
- name: metric
in: query
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetPortfolioChartResponse'
'400':
description: Invalid period or metric parameter
'401':
description: Authentication required
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/accounts/movements:
get:
tags:
- AccountsService
- Accounts
summary: Get user movements
description: |-
Get user movements.
Get the current user's ledger movements (transaction history) with
pagination and filtering support.
operationId: get_user_movements
parameters:
- name: page
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 10000
description: Page number (1-indexed)
- name: page_size
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 100
default: 20
description: Items per page (max 100)
- name: transaction_type
in: query
schema:
type: string
enum:
- DEPOSIT
- WITHDRAWAL
- TRADE
- FEE
- FUNDING
- LIQUIDATION
- INTEREST
- REWARD
- CHAIN_SYNC
minLength: 1
description: Transaction type
- name: entry_type
in: query
schema:
type: string
enum:
- CREDIT
- DEBIT
- LOCK
- UNLOCK
- FEE
minLength: 1
description: Ledger entry type
- name: asset_id
in: query
schema:
type: string
minLength: 1
format: uuid
description: Asset identifier (UUID)
- name: order_by
in: query
schema:
type: string
default: DESC
enum:
- ASC
- DESC
minLength: 1
description: Sort direction for created_at
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetMovementsResponse'
'400':
description: Invalid request
'401':
description: Authentication required
'404':
description: User not found
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/accounts/sub-accounts:
get:
tags:
- AccountsService
- Accounts
summary: List sub-accounts with balances
description: |-
List sub-accounts with balances.
List all sub-accounts with their token balances for a master account.
Only returns sub-accounts that belong to the same application as the
requesting user.
operationId: list_sub_accounts_with_balances
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListSubAccountsResponse'
'400':
description: Invalid request
'401':
description: Authentication required
'403':
description: Only master accounts can view sub-accounts
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/accounts/sub-accounts/limits:
post:
tags:
- AccountsService
- Account Limits
summary: Create sub-account limit
description: |-
Create sub-account limit.
Create a new limit for a sub-account. Only master accounts can create
limits for their sub-accounts.
operationId: create_sub_account_limit
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateLimitRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateLimitResponse'
'201':
description: Limit created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateLimitResponse'
'400':
description: Invalid request or limit already exists
'401':
description: Authentication required
'403':
description: Only master accounts can set sub-account limits
'404':
description: Sub-account relationship not found or asset not found
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/accounts/sub-accounts/{sub_account_id}/limits:
get:
tags:
- AccountsService
- Account Limits
summary: Get sub-account limits
description: |-
Get sub-account limits.
Get all limits for a sub-account. Users can only view limits for their
own accounts or their sub-accounts.
operationId: get_sub_account_limits
parameters:
- name: sub_account_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetLimitsResponse'
'400':
description: Invalid request
'401':
description: Authentication required
'403':
description: Only master accounts can view sub-account limits
'404':
description: Sub-account not found
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/accounts/sub-accounts/{sub_account_id}/limits/{asset_id}:
put:
tags:
- AccountsService
- Account Limits
summary: Update sub-account limit
description: |-
Update sub-account limit.
Update an existing limit for a sub-account. Only master accounts can
update limits for their sub-accounts.
operationId: update_sub_account_limit
parameters:
- name: sub_account_id
in: path
required: true
schema:
type: string
- name: asset_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateLimitRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateLimitResponse'
'400':
description: Invalid request
'401':
description: Authentication required
'403':
description: Only master accounts can update sub-account limits
'404':
description: Limit not found
'500':
description: Internal server error
security:
- bearerAuth: []
delete:
tags:
- AccountsService
- Account Limits
summary: Delete sub-account limit
description: |-
Delete sub-account limit.
Delete a limit for a sub-account. Only master accounts can delete limits
for their sub-accounts.
operationId: delete_sub_account_limit
parameters:
- name: sub_account_id
in: path
required: true
schema:
type: string
- name: asset_id
in: path
required: true
schema:
type: string
- name: limit_id
in: query
schema:
type: string
minLength: 1
format: uuid
description: Limit identifier (UUID)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteLimitResponse'
'400':
description: Invalid request
'401':
description: Authentication required
'403':
description: Only master accounts can delete sub-account limits
'404':
description: Limit not found
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/accounts/trades:
get:
tags:
- AccountsService
- Accounts
summary: Get user trade history
description: |-
Get user trades.
Get the authenticated user's trade history with pagination.
Returns trades where the user was either maker or taker, with
user-specific side and fee information.
operationId: get_user_trades
parameters:
- name: page
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 10000
description: Page number (1-indexed)
- name: page_size
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 100
default: 20
description: Items per page (max 100)
- name: trading_pair_id
in: query
schema:
type: string
minLength: 1
format: uuid
description: Trading pair identifier (UUID)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetUserTradesResponse'
'400':
description: Invalid request
'401':
description: Authentication required
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/applications/balances:
get:
tags:
- ApplicationsService
- Applications (Backend)
summary: List application balances
description: |-
List application balances.
Returns a paginated list of all user balances for this application.
Requires backend authentication via secret key.
operationId: list_application_balances
parameters:
- name: page
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 10000
description: Page number (1-indexed)
- name: page_size
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 100
default: 20
description: Items per page (max 100)
- name: user_id
in: query
schema:
type: string
minLength: 1
format: uuid
description: User identifier (UUID)
- name: asset_id
in: query
schema:
type: string
minLength: 1
format: uuid
description: Asset identifier (UUID)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListAppBalancesResponse'
'400':
description: Bad request
'401':
description: Unauthorized - Invalid or missing x-server-key
'500':
description: Internal server error
security:
- apiKey: []
/api/v1/applications/config:
get:
tags:
- ApplicationsService
- Applications
summary: Get application configuration
description: |-
Get application configuration.
Returns the configuration for the authenticated application including
allowed origins, webhook URL, and vault contract address.
operationId: get_application_config
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetConfigResponse'
'400':
description: Bad request
'401':
description: Unauthorized - Invalid or missing JWT
'404':
description: Application not found
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/applications/movements:
get:
tags:
- ApplicationsService
- Applications (Backend)
summary: List application movements
description: |-
List application movements.
Returns a paginated list of all ledger movements (deposits, withdrawals,
trades, etc.) for this application. Requires backend authentication via
secret key.
operationId: list_application_movements
parameters:
- name: page
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 10000
description: Page number (1-indexed)
- name: page_size
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 100
default: 20
description: Items per page (max 100)
- name: user_id
in: query
schema:
type: string
minLength: 1
format: uuid
description: User identifier (UUID)
- name: transaction_type
in: query
schema:
type: string
enum:
- DEPOSIT
- WITHDRAWAL
- TRADE
- FEE
- FUNDING
- LIQUIDATION
- INTEREST
- REWARD
- CHAIN_SYNC
minLength: 1
description: Transaction type
- name: entry_type
in: query
schema:
type: string
enum:
- CREDIT
- DEBIT
- LOCK
- UNLOCK
- FEE
minLength: 1
description: Ledger entry type
- name: asset_id
in: query
schema:
type: string
minLength: 1
format: uuid
description: Asset identifier (UUID)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListAppMovementsResponse'
'400':
description: Bad request
'401':
description: Unauthorized - Invalid or missing x-server-key
'500':
description: Internal server error
security:
- apiKey: []
/api/v1/applications/orders:
get:
tags:
- ApplicationsService
- Applications (Backend)
summary: List application orders
description: |-
List application orders.
Returns a paginated list of all orders for this application. Requires
backend authentication via secret key.
operationId: list_application_orders
parameters:
- name: page
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 10000
description: Page number (1-indexed)
- name: page_size
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 100
default: 20
description: Items per page (max 100)
- name: status
in: query
schema:
type: string
minLength: 1
description: Order status (single value or comma-separated list)
- name: user_id
in: query
schema:
type: string
minLength: 1
format: uuid
description: User identifier (UUID)
- name: trading_pair_id
in: query
schema:
type: string
minLength: 1
format: uuid
description: Trading pair identifier (UUID)
- name: side
in: query
schema:
type: string
enum:
- BUY
- SELL
minLength: 1
description: Order side
- name: order_type
in: query
schema:
type: string
enum:
- LIMIT
- MARKET
- STOP_LOSS
- TAKE_PROFIT
- STOP_LIMIT
- TRAILING_STOP
minLength: 1
description: Order type
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListAppOrdersResponse'
'400':
description: Bad request
'401':
description: Unauthorized - Invalid or missing x-server-key
'500':
description: Internal server error
security:
- apiKey: []
/api/v1/applications/users:
get:
tags:
- ApplicationsService
- Applications (Backend)
summary: List application users
description: |-
List application users.
Returns a paginated list of all users for this application. Requires
backend authentication via secret key.
operationId: list_application_users
parameters:
- name: page
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 10000
description: Page number (1-indexed)
- name: page_size
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 100
default: 20
description: Items per page (max 100)
- name: is_active
in: query
schema:
type: boolean
- name: account_type
in: query
schema:
type: string
enum:
- master
- sub
minLength: 1
description: Account type filter
- name: address
in: query
schema:
type: string
minLength: 1
description: Wallet address
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListAppUsersResponse'
'400':
description: Bad request
'401':
description: Unauthorized - Invalid or missing x-server-key
'500':
description: Internal server error
security:
- apiKey: []
/api/v1/auth/backend:
post:
tags:
- AuthService
- Auth
summary: Backend service authentication
description: |-
Backend service authentication.
Authenticate a backend service using a secret key. Returns a long-lived
access token for server-to-server API access.
operationId: authenticate_backend
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BackendAuthRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BackendAuthResponse'
'400':
description: Invalid request parameters
'401':
description: Invalid secret key or inactive application
'500':
description: Internal server error
/api/v1/auth/challenge:
post:
tags:
- AuthService
- Auth
summary: Create authentication challenge
description: |-
Create authentication challenge.
Generate a cryptographic challenge (nonce) for wallet-based authentication.
The user must sign the returned message with their private key to prove
ownership of the wallet.
operationId: create_challenge
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ChallengeRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ChallengeResponse'
'400':
description: Invalid request parameters
'403':
description: Origin not allowed for this application
'404':
description: Invalid client_id
'500':
description: Internal server error
/api/v1/auth/refresh:
post:
tags:
- AuthService
- Auth
summary: Refresh access token
description: |-
Refresh access token.
Generate a new access token using a valid refresh token. The refresh
token remains valid for future use.
operationId: refresh_token
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RefreshRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RefreshResponse'
'400':
description: Invalid request parameters
'401':
description: Invalid, expired, or revoked refresh token
'404':
description: User not found
'500':
description: Internal server error
/api/v1/auth/revoke:
post:
tags:
- AuthService
- Auth
summary: Revoke current session
description: |-
Revoke current session.
Revoke the current authenticated session, invalidating the access token.
The user will need to authenticate again.
operationId: revoke_session
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RevokeRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RevokeResponse'
'400':
description: Request body must be empty
'401':
description: Missing or invalid authorization token
'404':
description: Session not found
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/auth/verify:
post:
tags:
- AuthService
- Auth
summary: Verify signature and authenticate
description: |-
Verify signature and authenticate.
Verify the signed challenge message and create an authenticated session.
Returns JWT tokens for subsequent API access.
operationId: verify_signature
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyResponse'
'400':
description: Invalid request parameters, nonce expired, or already used
'401':
description: Invalid signature
'403':
description: Origin not allowed for this application
'404':
description: Invalid nonce or client_id
'500':
description: Internal server error
/api/v1/faucet/mint:
post:
tags:
- FaucetService
- Faucet
summary: Mint all testnet tokens
description: |-
Mint all testnet tokens.
Mint all available testnet tokens to the authenticated user's address.
Rate limited per 24 hours.
operationId: mint_tokens
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MintTokensResponse'
'400':
description: Invalid request
'401':
description: Authentication required
'429':
description: Rate limit exceeded
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/fees/simulate:
get:
tags:
- FeesService
- Fees
summary: Simulate fees for a potential order
description: |-
Simulate fees for a potential order.
Returns exact fee breakdown for a specific order before placing it,
including Monaco protocol fees, application fees, total amounts,
and the maximum quantity affordable at the given price.
operationId: simulate_fees
parameters:
- name: trading_pair_id
in: query
schema:
type: string
minLength: 1
format: uuid
description: Trading pair identifier (UUID)
required: true
- name: side
in: query
schema:
type: string
enum:
- BUY
- SELL
minLength: 1
description: Order side
required: true
- name: price
in: query
schema:
type: string
minLength: 1
description: Price as decimal string
required: true
- name: quantity
in: query
schema:
type: string
minLength: 1
description: Quantity as decimal string
required: true
- name: order_type
in: query
schema:
type: string
enum:
- LIMIT
- MARKET
- STOP_LOSS
- TAKE_PROFIT
- STOP_LIMIT
- TRAILING_STOP
minLength: 1
description: Order type
- name: slippage_tolerance_bps
in: query
schema:
type: integer
format: int32
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SimulateFeesResponse'
'400':
description: Bad request (e.g., slippage with LIMIT order)
'401':
description: Authentication required
'404':
description: Trading pair or application not found
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/market/pairs:
get:
tags:
- MarketService
- Market
summary: Trading Pairs
description: |-
Trading Pairs
Get paginated list of trading pairs with optional filtering by market
type, base token, quote token, and active status.
operationId: list_trading_pairs
parameters:
- name: page
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 10000
description: Page number (1-indexed)
- name: page_size
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 100
default: 20
description: Items per page (max 100)
- name: market_type
in: query
schema:
type: string
enum:
- SPOT
- MARGIN
minLength: 1
description: Filter by market type
- name: base_token
in: query
schema:
type: string
- name: quote_token
in: query
schema:
type: string
- name: is_active
in: query
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListTradingPairsResponse'
'400':
description: Invalid market type parameter
'500':
description: Internal server error
/api/v1/market/pairs/charts/candlestick/{trading_pair_id}/{interval}:
get:
tags:
- MarketService
- Market
summary: Candlestick Data
description: |-
Candlestick Data
Get OHLCV (Open, High, Low, Close, Volume) candlestick data for a
trading pair with configurable interval and time range.
operationId: get_candles
parameters:
- name: trading_pair_id
in: path
required: true
schema:
type: string
- name: interval
in: path
required: true
schema:
type: string
- name: start_time
in: query
schema:
type: integer
minimum: 0
maximum: 4102444800000
format: int64
description: Start time as Unix timestamp (milliseconds)
- name: end_time
in: query
schema:
type: integer
minimum: 0
maximum: 4102444800000
format: int64
description: End time as Unix timestamp (milliseconds)
- name: limit
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 1000
default: 100
description: Max candles to return (max 1000)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetCandlesResponse'
'400':
description: Invalid parameters
'404':
description: Trading pair not found or inactive
'500':
description: Internal server error
/api/v1/market/pairs/{trading_pair_id}:
get:
tags:
- MarketService
- Market
summary: Trading Pair By ID
description: |-
Trading Pair By ID
Get a specific trading pair by its UUID.
operationId: get_trading_pair_by_id
parameters:
- name: trading_pair_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetTradingPairResponse'
'404':
description: Trading pair not found
'500':
description: Internal server error
/api/v1/market/pairs/{trading_pair_id}/metadata:
get:
tags:
- MarketService
- Market
summary: Market Metadata
description: |-
Market Metadata
Returns current price (from latest candle), 24h statistics (high, low,
volume, change), and market initialization timestamp. 24h fields will
be null if less than 24 hours of data available.
operationId: get_market_metadata
parameters:
- name: trading_pair_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetMarketMetadataResponse'
'404':
description: Trading pair not found
'500':
description: Internal server error
/api/v1/orderbook/{trading_pair_id}:
get:
tags:
- OrderbookService
- Orderbook
summary: Orderbook Snapshot
description: |-
Orderbook Snapshot
Get the complete orderbook snapshot for a trading pair showing all bids
and asks with their price levels. This is a public endpoint that does
not require authentication.
operationId: get_orderbook_snapshot
parameters:
- name: trading_pair_id
in: path
required: true
schema:
type: string
- name: levels
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 100
default: 20
description: Number of price levels (max 100)
- name: trading_mode
in: query
schema:
type: string
enum:
- SPOT
- MARGIN
minLength: 1
description: Trading mode
- name: magnitude
in: query
schema:
type: string
enum:
- '0.0001'
- '0.001'
- '0.01'
- '0.1'
- '1'
- '10'
- '100'
- '1000'
- '10000'
minLength: 1
description: Price grouping magnitude
- name: denomination
in: query
schema:
type: string
enum:
- base
- quote
minLength: 1
description: Price denomination
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetOrderbookResponse'
'400':
description: Invalid magnitude or denomination value
'404':
description: Trading pair not found
'500':
description: Matching engine not initialized or internal error
/api/v1/orders:
get:
tags:
- OrdersService
- Orders
summary: Get user orders
description: |-
Get user orders.
Get orders for the authenticated user with pagination and optional
filtering by status and trading pair.
operationId: get_orders
parameters:
- name: page
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 10000
description: Page number (1-indexed)
- name: page_size
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 100
default: 20
description: Items per page (max 100)
- name: status
in: query
schema:
type: string
minLength: 1
description: Order status (single value or comma-separated list)
- name: trading_pair_id
in: query
schema:
type: string
minLength: 1
format: uuid
description: Trading pair identifier (UUID)
- name: order_by
in: query
schema:
type: string
default: DESC
enum:
- ASC
- DESC
minLength: 1
description: Sort direction for created_at
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListOrdersResponse'
'400':
description: Invalid query parameters
'401':
description: Authentication required
'403':
description: User does not belong to application
'404':
description: User not found
'500':
description: Internal server error
security:
- bearerAuth: []
post:
tags:
- OrdersService
- Orders
summary: Create new order
description: |-
Create new order.
Create a new order and process it through the matching engine. The order
will be matched against existing orders in the orderbook.
operationId: create_order
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderResponse'
'400':
description: Invalid order parameters or insufficient balance
'401':
description: Authentication required
'500':
description: Internal server error or matching engine failure
security:
- bearerAuth: []
/api/v1/orders/batch-cancel:
post:
tags:
- OrdersService
- Orders
summary: Batch cancel specific orders
description: |-
Batch cancel specific orders.
Cancel multiple specific orders by their IDs. For canceling all orders,
use /batch-cancel-all or /batch-cancel-all/{trading_pair_id}.
operationId: batch_cancel_orders
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCancelOrdersRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCancelOrdersResponse'
'400':
description: Invalid request - order_ids is required
'401':
description: Authentication required
'500':
description: Internal server error or matching engine failure
security:
- bearerAuth: []
/api/v1/orders/batch-cancel-all:
post:
tags:
- OrdersService
- Orders
summary: Cancel all orders
description: |-
Cancel all orders.
Cancel all active orders for the authenticated user. To cancel orders
for a specific trading pair, use /batch-cancel-all/{trading_pair_id}.
operationId: batch_cancel_all
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCancelAllResponse'
'401':
description: Authentication required
'500':
description: Internal server error or matching engine failure
security:
- bearerAuth: []
/api/v1/orders/batch-cancel-all/{trading_pair_id}:
post:
tags:
- OrdersService
- Orders
summary: Cancel all orders for a trading pair
description: |-
Cancel all orders for a trading pair.
Cancel all active orders for the authenticated user on a specific
trading pair.
operationId: batch_cancel_all_by_pair
parameters:
- name: trading_pair_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCancelAllResponse'
'400':
description: Invalid trading pair ID
'401':
description: Authentication required
'500':
description: Internal server error or matching engine failure
security:
- bearerAuth: []
/api/v1/orders/batch-create:
post:
tags:
- OrdersService
- Orders
summary: Batch create orders
description: |-
Batch create orders.
Create multiple orders in a single batch. Each order is processed
sequentially through the matching engine.
operationId: batch_create_orders
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCreateOrdersRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCreateOrdersResponse'
'400':
description: Invalid request
'401':
description: Authentication required
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/orders/batch-replace:
post:
tags:
- OrdersService
- Orders
summary: Batch replace orders
description: |-
Batch replace orders.
Replace multiple orders in a single batch. Each order is processed
sequentially through the matching engine.
operationId: batch_replace_orders
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BatchReplaceOrdersRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BatchReplaceOrdersResponse'
'400':
description: Invalid request
'401':
description: Authentication required
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/orders/cancel:
post:
tags:
- OrdersService
- Orders
summary: Cancel existing order
description: |-
Cancel existing order.
Cancel an existing order and unlock the reserved funds. Only orders that
are not yet filled can be cancelled.
operationId: cancel_order
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CancelOrderRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CancelOrderResponse'
'400':
description: Invalid order ID or order already filled/cancelled
'401':
description: Authentication required or order doesn't belong to user
'404':
description: Order not found
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/orders/{order_id}:
get:
tags:
- OrdersService
- Orders
summary: Get order by ID
description: |-
Get order by ID.
Get a single order by its ID. Users can only access their own orders.
operationId: get_order_by_id
parameters:
- name: order_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetOrderResponse'
'400':
description: Invalid order ID format
'401':
description: Authentication required
'403':
description: User does not have permission to view this order
'404':
description: Order not found or user not found
'500':
description: Internal server error
security:
- bearerAuth: []
put:
tags:
- OrdersService
- Orders
summary: Replace existing order
description: |-
Replace existing order.
Replaces an existing order with new parameters by canceling the original
order and creating a new one with the updated price/quantity. Priority is
lost in the order book.
operationId: replace_order
parameters:
- name: order_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReplaceOrderRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReplaceOrderResponse'
'400':
description: Invalid order ID, order cannot be replaced, or insufficient balance
'401':
description: Authentication required or order doesn't belong to user
'404':
description: Order not found
'500':
description: Internal server error
security:
- bearerAuth: []
/api/v1/trades/by-id/{trade_id}:
get:
tags:
- TradesService
- Trades
summary: Get Trade by ID
description: |-
Get Trade by ID
Retrieve a single trade by its unique identifier.
operationId: get_trade_by_id
parameters:
- name: trade_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetTradeByIdResponse'
'400':
description: Invalid trade ID
'404':
description: Trade not found
'500':
description: Internal server error
/api/v1/trades/{trading_pair_id}:
get:
tags:
- TradesService
- Trades
summary: Recent Trades
description: |-
Recent Trades
Get recent trades for a trading pair sorted by execution time.
operationId: get_trades
parameters:
- name: trading_pair_id
in: path
required: true
schema:
type: string
- name: page
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 10000
description: Page number (1-indexed)
- name: page_size
in: query
schema:
type: integer
format: uint32
minimum: 1
maximum: 100
default: 25
description: Max trades to return (max 100)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetTradesResponse'
'400':
description: Invalid trading pair ID
'404':
description: Trading pair not found
'500':
description: Internal server error
/api/v1/whitelist:
post:
tags:
- WhitelistService
- Whitelist
summary: Submit whitelist application
description: |-
Submit whitelist application.
Submit a whitelist application to join Monaco Protocol. The user will be
created with is_active = false and will need to be approved by an admin.
operationId: submit_whitelist
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitWhitelistRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitWhitelistResponse'
'400':
description: Invalid request parameters
'409':
description: Wallet address or email already registered
'500':
description: Internal server error
/health:
get:
tags:
- HealthService
- Health
summary: Health check
description: |-
Health check.
Returns the current health status of the API gateway and its connected
services. Can be used for monitoring and load balancer health checks.
operationId: health_check
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PublicHealthCheckResponse'
'503':
description: Service is unhealthy
components:
schemas:
AccountBalance:
type: object
properties:
token:
nullable: true
type: string
description: Token contract address
symbol:
example: USDC
type: string
description: Token symbol
nullable: true
decimals:
example: 6
type: integer
description: Token decimal places
format: int32
nullable: true
available_balance:
example: '1000.50'
type: string
description: Available (unlocked) balance in token units
nullable: true
locked_balance:
example: '50.25'
type: string
description: Balance locked in open orders
nullable: true
total_balance:
example: '1050.75'
type: string
description: Total balance (available + locked)
nullable: true
available_balance_raw:
example: '1000500000'
type: string
description: Raw available balance in smallest token unit
nullable: true
locked_balance_raw:
example: '50250000'
type: string
description: Raw locked balance in smallest token unit
nullable: true
asset_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Asset UUID
format: uuid
nullable: true
AppUser:
type: object
properties:
id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: User UUID
format: uuid
nullable: true
address:
maxLength: 42
type: string
description: Wallet address
nullable: true
pattern: ^0x[0-9a-fA-F]{40}$
minLength: 42
username:
example: trader123
type: string
description: Display username
nullable: true
account_type:
example: master
type: string
description: 'Account type: master or sub'
nullable: true
can_withdraw:
example: true
type: boolean
description: Whether the user is allowed to withdraw
nullable: true
created_at:
example: 2023-11-13T10:30:00Z
type: string
description: Account creation timestamp (ISO 8601)
nullable: true
email:
type: string
description: Email address
nullable: true
is_active:
example: true
type: boolean
description: Whether the user account is active
nullable: true
is_banned:
example: false
type: boolean
description: Whether the user is banned
nullable: true
master_account_id:
type: string
description: Master account ID (for sub-accounts)
format: uuid
nullable: true
updated_at:
example: 2023-11-13T10:35:00Z
type: string
description: Last update timestamp (ISO 8601)
nullable: true
ApplicationBalance:
type: object
properties:
available_balance:
type: string
description: Available balance for trading
nullable: true
created_at:
type: string
description: Balance creation timestamp (ISO 8601)
nullable: true
decimals:
type: integer
description: Token decimals
format: int32
nullable: true
id:
type: string
description: Balance UUID
format: uuid
nullable: true
last_sync_at:
type: string
description: Last sync timestamp (ISO 8601)
nullable: true
last_sync_block:
type: string
description: Last sync block number
nullable: true
locked_balance:
type: string
description: Locked balance
nullable: true
margin_locked:
type: string
description: Margin locked balance
nullable: true
on_chain_balance:
type: string
description: On-chain balance
nullable: true
symbol:
type: string
description: Token symbol
nullable: true
token:
type: string
description: Token address
nullable: true
total_balance:
type: string
description: Total balance
nullable: true
updated_at:
type: string
description: Balance last update timestamp (ISO 8601)
nullable: true
user_id:
type: string
description: User UUID who owns this balance
format: uuid
nullable: true
ApplicationMovement:
type: object
properties:
amount:
type: string
description: Transaction amount
nullable: true
balance_after:
type: string
description: Balance after this transaction
nullable: true
balance_before:
type: string
description: Balance before this transaction
nullable: true
balance_id:
type: string
description: Balance UUID this movement affects
format: uuid
nullable: true
block_number:
type: string
description: Blockchain block number
nullable: true
created_at:
type: string
description: Transaction timestamp (ISO 8601)
nullable: true
description:
type: string
description: Human readable description
nullable: true
entry_type:
type: string
description: Type of ledger entry
nullable: true
id:
type: string
description: Movement UUID
format: uuid
nullable: true
locked_after:
type: string
description: Locked balance after transaction
nullable: true
locked_before:
type: string
description: Locked balance before transaction
nullable: true
reference_id:
type: string
description: Reference identifier for related operations
format: uuid
nullable: true
reference_type:
type: string
description: Reference type
nullable: true
token:
type: string
description: Token address
nullable: true
transaction_type:
type: string
description: Type of transaction
nullable: true
tx_hash:
type: string
description: Blockchain transaction hash
nullable: true
user_id:
type: string
description: User UUID who owns this movement
format: uuid
nullable: true
ApplicationOrder:
type: object
properties:
id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Order UUID
format: uuid
nullable: true
user_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: User UUID who placed the order
format: uuid
nullable: true
trading_pair_id:
example: 456e7890-e12b-12d3-a456-426614174000
type: string
description: Trading pair UUID
format: uuid
nullable: true
order_type:
example: LIMIT
type: string
description: 'Order type: LIMIT, MARKET, STOP_LOSS, TAKE_PROFIT, STOP_LIMIT, or TRAILING_STOP'
nullable: true
side:
example: BUY
type: string
description: 'Order side: BUY or SELL'
nullable: true
price:
example: '35000.00'
type: string
description: Order price (null for market orders)
nullable: true
quantity:
example: '0.5'
type: string
description: Order quantity (normalized for display)
nullable: true
quantity_raw:
example: '500000000'
type: string
description: Order quantity in raw format (for precision)
nullable: true
filled_quantity:
example: '0.2'
type: string
description: Filled quantity (normalized for display)
nullable: true
filled_quantity_raw:
example: '200000000'
type: string
description: Filled quantity in raw format
nullable: true
average_fill_price:
example: '35050.00'
type: string
description: Volume-weighted average fill price
nullable: true
status:
example: SUBMITTED
type: string
description: Order status
nullable: true
trading_mode:
example: SPOT
type: string
description: 'Trading mode: SPOT or MARGIN'
nullable: true
time_in_force:
example: GTC
type: string
description: 'Time in force: GTC, IOC, or FOK'
nullable: true
created_at:
example: 2023-11-13T10:30:00Z
type: string
description: Order creation timestamp (ISO 8601)
nullable: true
updated_at:
example: 2023-11-13T10:35:00Z
type: string
description: Order last update timestamp (ISO 8601)
nullable: true
BackendAuthRequest:
required:
- secret_key
type: object
properties:
secret_key:
example: sk_live_abc123def456
type: string
description: Backend secret key (sk_xxx)
additionalProperties: false
BackendAuthResponse:
type: object
properties:
app_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Application UUID
nullable: true
client_id:
example: monaco-frontend
type: string
description: Application client identifier
nullable: true
name:
example: Monaco Trading Frontend
type: string
description: Application display name
nullable: true
BatchCancelAllResponse:
type: object
properties:
total_requested:
example: 10
type: integer
description: Number of orders requested to cancel
format: int32
nullable: true
total_cancelled:
example: 10
type: integer
description: Number of orders successfully cancelled
format: int32
nullable: true
total_failed:
example: 0
type: integer
description: Number of cancellations that failed
format: int32
nullable: true
results:
type: array
items:
$ref: '#/components/schemas/BatchCancelResult'
nullable: true
BatchCancelError:
type: object
properties:
code:
example: ORDER_ALREADY_FILLED
type: string
description: Machine-readable error code
nullable: true
message:
example: Order has already been fully filled
type: string
description: Human-readable error message
nullable: true
BatchCancelOrdersRequest:
required:
- order_ids
type: object
properties:
order_ids:
minItems: 1
type: array
items:
type: string
minLength: 1
format: uuid
description: List of order UUIDs to cancel
additionalProperties: false
BatchCancelOrdersResponse:
type: object
properties:
total_requested:
example: 5
type: integer
description: Number of orders requested to cancel
format: int32
nullable: true
total_cancelled:
example: 4
type: integer
description: Number of orders successfully cancelled
format: int32
nullable: true
total_failed:
example: 1
type: integer
description: Number of cancellations that failed
format: int32
nullable: true
results:
type: array
items:
$ref: '#/components/schemas/BatchCancelResult'
nullable: true
BatchCancelResult:
type: object
properties:
order_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Order UUID
format: uuid
nullable: true
cancelled_at:
example: 2023-11-13T10:35:00Z
type: string
description: Cancellation timestamp (ISO 8601). Present on success; absent when `error` is set.
nullable: true
error:
$ref: '#/components/schemas/BatchCancelError'
BatchCreateError:
type: object
properties:
code:
example: INSUFFICIENT_BALANCE
type: string
description: Machine-readable error code
nullable: true
message:
example: Insufficient balance to place order
type: string
description: Human-readable error message
nullable: true
BatchCreateOrderItem:
required:
- trading_pair_id
- order_type
- side
- quantity
type: object
properties:
trading_pair_id:
example: 456e7890-e12b-12d3-a456-426614174000
type: string
description: Trading pair UUID
format: uuid
order_type:
example: LIMIT
type: string
description: 'Order type: LIMIT or MARKET'
side:
example: BUY
type: string
description: 'Order side: BUY or SELL'
price:
example: '35000.00'
type: string
description: Limit price as decimal string (required for LIMIT orders)
nullable: true
quantity:
example: '0.5'
type: string
description: Order quantity as decimal string
trading_mode:
example: SPOT
type: string
description: 'Trading mode: SPOT or MARGIN (default: SPOT)'
nullable: true
slippage_tolerance_bps:
example: 50
maximum: 10000
type: integer
description: Maximum slippage tolerance in basis points (market orders only)
format: int32
nullable: true
use_master_balance:
example: false
type: boolean
description: Use master account balance for sub-account orders
nullable: true
expiration_date:
example: 2026-06-01T00:00:00Z
type: string
description: Order expiration date (ISO 8601, must be in the future)
nullable: true
time_in_force:
example: GTC
type: string
description: 'Time in force: GTC, IOC, or FOK'
nullable: true
additionalProperties: false
BatchCreateOrdersRequest:
required:
- orders
type: object
properties:
orders:
minItems: 1
type: array
items:
$ref: '#/components/schemas/BatchCreateOrderItem'
additionalProperties: false
BatchCreateOrdersResponse:
type: object
properties:
total_requested:
example: 5
type: integer
description: Number of orders requested to create
format: int32
nullable: true
total_succeeded:
example: 4
type: integer
description: Number of orders successfully created
format: int32
nullable: true
total_failed:
example: 1
type: integer
description: Number of creations that failed
format: int32
nullable: true
results:
type: array
items:
$ref: '#/components/schemas/BatchCreateResult'
nullable: true
BatchCreateResult:
type: object
properties:
order_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Created order UUID
format: uuid
nullable: true
match_result:
$ref: '#/components/schemas/MatchResult'
error:
$ref: '#/components/schemas/BatchCreateError'
BatchReplaceError:
type: object
properties:
code:
example: ORDER_NOT_FOUND
type: string
description: Machine-readable error code
nullable: true
message:
example: Order not found or already filled
type: string
description: Human-readable error message
nullable: true
BatchReplaceOrderItem:
required:
- order_id
type: object
properties:
order_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Order UUID to replace
format: uuid
price:
example: '35500.00'
type: string
description: New limit price (if changing)
nullable: true
quantity:
example: '0.7'
type: string
description: New quantity (if changing)
nullable: true
use_master_balance:
example: false
type: boolean
description: Use master account balance for sub-account orders
nullable: true
additionalProperties: false
BatchReplaceOrdersRequest:
required:
- orders
type: object
properties:
orders:
minItems: 1
type: array
items:
$ref: '#/components/schemas/BatchReplaceOrderItem'
additionalProperties: false
BatchReplaceOrdersResponse:
type: object
properties:
total_requested:
example: 3
type: integer
description: Number of orders requested to replace
format: int32
nullable: true
total_succeeded:
example: 3
type: integer
description: Number of orders successfully replaced
format: int32
nullable: true
total_failed:
example: 0
type: integer
description: Number of replacements that failed
format: int32
nullable: true
results:
type: array
items:
$ref: '#/components/schemas/BatchReplaceResult'
nullable: true
BatchReplaceResult:
type: object
properties:
original_order_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Original order UUID that was replaced
format: uuid
nullable: true
new_order_id:
example: 987e6543-e21b-12d3-a456-426614174000
type: string
description: New replacement order UUID (if successful)
format: uuid
nullable: true
updated_fields:
$ref: '#/components/schemas/UpdatedFields'
match_result:
$ref: '#/components/schemas/MatchResult'
error:
$ref: '#/components/schemas/BatchReplaceError'
CancelOrderRequest:
required:
- order_id
type: object
properties:
order_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Order UUID to cancel
format: uuid
additionalProperties: false
CancelOrderResponse:
type: object
properties:
order_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Cancelled order UUID
format: uuid
nullable: true
status:
example: SUCCESS
type: string
description: 'Result status: SUCCESS or FAILED'
nullable: true
message:
example: Order cancelled successfully
type: string
description: Human-readable status message
nullable: true
Candle:
type: object
properties:
timestamp:
nullable: true
type: string
description: Unix timestamp for the start of the candle period in milliseconds
open:
example: '35000.00'
type: string
description: Opening price
nullable: true
high:
example: '35500.00'
type: string
description: Highest price during the period
nullable: true
low:
example: '34800.00'
type: string
description: Lowest price during the period
nullable: true
close:
example: '35200.00'
type: string
description: Closing price
nullable: true
volume:
example: '125.5'
type: string
description: Base token volume traded during the period
nullable: true
quote_volume:
example: '4412600.00'
type: string
description: Quote token volume traded during the period
nullable: true
trade_count:
example: 342
type: integer
description: Number of trades during the period
format: uint32
nullable: true
close_timestamp_ms:
nullable: true
type: string
description: Unix timestamp for the end of the candle period in milliseconds
ChallengeRequest:
required:
- address
type: object
properties:
address:
description: Ethereum wallet address
maxLength: 42
minLength: 42
pattern: ^0x[0-9a-fA-F]{40}$
type: string
client_id:
example: monaco-frontend
type: string
description: Optional application identifier
nullable: true
chain_id:
nullable: true
type: string
description: Optional chain ID supplied by SDK clients
additionalProperties: false
ChallengeResponse:
type: object
properties:
nonce:
example: abc123def456
type: string
description: Unique challenge nonce
nullable: true
message:
example: Sign this message to authenticate with Monaco Protocol...
type: string
description: Message to sign
nullable: true
expires_at:
example: 1699876543
type: integer
description: Unix timestamp when challenge expires
format: int32
nullable: true
ChartDataPoint:
type: object
properties:
timestamp:
example: 2026-02-18T00:00:00Z
type: string
description: Bucket timestamp (ISO 8601)
nullable: true
value:
example: '-0.002'
type: string
description: Metric value for this bucket
nullable: true
CreateLimitRequest:
required:
- sub_account_id
- asset_id
- max_amount
type: object
properties:
sub_account_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Sub-account UUID to create the limit for
format: uuid
asset_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Asset UUID to limit
format: uuid
max_amount:
example: '1000.00'
minLength: 1
pattern: ^-?[0-9]{1,28}(\.[0-9]{1,18})?$
type: string
description: Maximum amount allowed in token units
daily_limit:
example: '500.00'
minLength: 1
pattern: ^-?[0-9]{1,28}(\.[0-9]{1,18})?$
type: string
description: Maximum daily spending limit in token units
nullable: true
additionalProperties: false
CreateLimitResponse:
type: object
properties:
limit:
$ref: '#/components/schemas/SubAccountLimit'
CreateOrderRequest:
required:
- trading_pair_id
- order_type
- side
- quantity
type: object
properties:
trading_pair_id:
example: afae0e16-2d05-4ee9-9ee8-afae0e162d05
type: string
description: Trading pair UUID
format: uuid
order_type:
example: LIMIT
type: string
description: 'Order type: LIMIT or MARKET'
side:
example: BUY
type: string
description: 'Order side: BUY or SELL'
price:
example: '35000.00'
type: string
description: Limit price as decimal string (required for LIMIT orders)
nullable: true
quantity:
example: '0.5'
type: string
description: Order quantity as decimal string
trading_mode:
example: SPOT
type: string
description: 'Trading mode: SPOT or MARGIN (default: SPOT)'
nullable: true
slippage_tolerance_bps:
example: 50
maximum: 10000
type: integer
description: Maximum slippage tolerance in basis points (market orders only)
format: int32
nullable: true
use_master_balance:
example: false
type: boolean
description: Use master account balance for sub-account orders
nullable: true
expiration_date:
example: 2026-06-01T00:00:00Z
type: string
description: Order expiration date (ISO 8601, must be in the future)
nullable: true
time_in_force:
example: GTC
type: string
description: 'Time in force: GTC, IOC, or FOK'
nullable: true
additionalProperties: false
CreateOrderResponse:
type: object
properties:
order_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Created order UUID
format: uuid
nullable: true
status:
example: SUCCESS
type: string
description: 'Result status: SUCCESS or FAILED'
nullable: true
message:
example: Order created successfully
type: string
description: Human-readable status message
nullable: true
match_result:
$ref: '#/components/schemas/MatchResult'
DeleteLimitResponse:
type: object
properties:
message:
example: Limit deleted successfully
type: string
description: Human-readable status message
nullable: true
ExecutionPriceRange:
type: object
properties:
best_price:
example: '2045.00'
type: string
description: Best execution price achieved
nullable: true
worst_price:
example: '2052.00'
type: string
description: Worst execution price in the fill
nullable: true
FailedMint:
type: object
properties:
asset_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Asset UUID
nullable: true
format: uuid
symbol:
example: WBTC
type: string
description: Token symbol
nullable: true
error:
example: Mint transaction failed
type: string
description: Error message describing why the mint failed
nullable: true
GetBalanceByAssetResponse:
type: object
properties:
token:
nullable: true
type: string
description: Token contract address
symbol:
example: USDC
type: string
description: Token symbol
nullable: true
decimals:
example: 6
type: integer
description: Token decimal places
format: int32
nullable: true
available_balance:
example: '1000.50'
type: string
description: Available (unlocked) balance in token units
nullable: true
locked_balance:
example: '50.25'
type: string
description: Balance locked in open orders
nullable: true
total_balance:
example: '1050.75'
type: string
description: Total balance (available + locked)
nullable: true
available_balance_raw:
example: '1000500000'
type: string
description: Raw available balance in smallest token unit
nullable: true
locked_balance_raw:
example: '50250000'
type: string
description: Raw locked balance in smallest token unit
nullable: true
asset_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Asset UUID
format: uuid
nullable: true
GetBalancesResponse:
type: object
properties:
balances:
type: array
items:
$ref: '#/components/schemas/AccountBalance'
nullable: true
total:
example: 5
type: integer
description: Total number of balances
format: uint32
nullable: true
page:
example: 1
type: integer
description: Current page number
format: uint32
nullable: true
page_size:
example: 20
type: integer
description: Items per page
format: uint32
nullable: true
total_pages:
example: 1
type: integer
description: Total number of pages
format: uint32
nullable: true
GetCandlesResponse:
type: object
properties:
candles:
type: array
items:
$ref: '#/components/schemas/Candle'
nullable: true
description: OHLCV candlestick data.
GetConfigResponse:
type: object
properties:
id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Application UUID
nullable: true
name:
example: Monaco
type: string
description: Application display name
nullable: true
allowed_origins:
type: array
items:
type: string
minLength: 1
description: List of allowed origins for CORS
nullable: true
webhook_url:
type: string
description: Webhook URL for notifications
nullable: true
vault_contract_address:
nullable: true
type: string
description: Vault contract address for this application
client_id:
example: 6fe0da813f1a4adcbe675d52ca530a43
type: string
description: Application client ID, embedded in on-chain deposit calls
nullable: true
GetLimitsResponse:
type: object
properties:
limits:
type: array
items:
$ref: '#/components/schemas/SubAccountLimit'
nullable: true
GetMarketMetadataResponse:
type: object
properties:
base_icon_url:
example: https://assets.0xmonaco.com/icons/btc.svg
type: string
description: URL for the base token icon
nullable: true
high_24h:
example: '96500.00'
type: string
description: Highest price in the last 24 hours
nullable: true
last_price:
example: '95432.50'
type: string
description: Most recent trade price
nullable: true
last_price_timestamp:
example: '1736742000000'
type: string
description: Timestamp of the last trade (ms since epoch)
nullable: true
low_24h:
example: '94200.00'
type: string
description: Lowest price in the last 24 hours
nullable: true
market_initialization_timestamp:
example: '1735000000000'
type: string
description: When this market was first initialized (ms since epoch)
nullable: true
price_change_24h:
example: '1232.50'
type: string
description: Absolute price change in the last 24 hours
nullable: true
price_change_percent_24h:
example: '1.31'
type: string
description: Percentage price change in the last 24 hours
nullable: true
quote_icon_url:
example: https://assets.0xmonaco.com/icons/usdc.svg
type: string
description: URL for the quote token icon
nullable: true
symbol:
example: BTC/USDC
type: string
description: Trading pair symbol
nullable: true
volume_24h:
example: '1234.5678'
type: string
description: Base token volume in the last 24 hours
nullable: true
description: Market metadata with current price and 24h statistics.
GetMovementsResponse:
type: object
properties:
movements:
type: array
items:
$ref: '#/components/schemas/LedgerMovement'
nullable: true
total:
example: 150
type: integer
description: Total number of movements
format: uint32
nullable: true
page:
example: 1
type: integer
description: Current page number
format: uint32
nullable: true
page_size:
example: 20
type: integer
description: Items per page
format: uint32
nullable: true
total_pages:
example: 8
type: integer
description: Total number of pages
format: uint32
nullable: true
GetOrderResponse:
type: object
properties:
id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Order UUID
format: uuid
nullable: true
trading_pair_id:
example: 456e7890-e12b-12d3-a456-426614174000
type: string
description: Trading pair UUID
format: uuid
nullable: true
order_type:
example: LIMIT
type: string
description: 'Order type: LIMIT or MARKET'
nullable: true
side:
example: BUY
type: string
description: 'Order side: BUY or SELL'
nullable: true
price:
example: '35000.00'
type: string
description: Limit price (null for market orders)
nullable: true
quantity:
example: '0.5'
type: string
description: Original order quantity
nullable: true
filled_quantity:
example: '0.2'
type: string
description: Quantity filled so far
nullable: true
average_fill_price:
example: '35050.00'
type: string
description: Volume-weighted average fill price
nullable: true
status:
example: PARTIALLY_FILLED
type: string
description: 'Order status: SUBMITTED, PARTIALLY_FILLED, FILLED, CANCELLED, REJECTED, or EXPIRED'
nullable: true
trading_mode:
example: SPOT
type: string
description: 'Trading mode: SPOT or MARGIN'
nullable: true
time_in_force:
example: GTC
type: string
description: 'Time in force: GTC, IOC, or FOK'
nullable: true
created_at:
example: 2023-11-13T10:30:00Z
type: string
description: Order creation timestamp (ISO 8601)
nullable: true
updated_at:
example: 2023-11-13T10:35:00Z
type: string
description: Last update timestamp (ISO 8601)
nullable: true
expiration_date:
example: 2023-11-13T10:35:00Z
type: string
description: Order expiration date (ISO 8601)
nullable: true
application_taker_fee:
example: '5'
type: string
description: Application taker fee in bps
nullable: true
monaco_taker_fee:
example: '10'
type: string
description: Monaco protocol taker fee in bps
nullable: true
monaco_maker_rebate:
example: '-2'
type: string
description: Monaco maker rebate in bps (negative)
nullable: true
total_taker_fees:
example: '2.63'
type: string
description: Total taker fees charged in quote token
nullable: true
taker_total_payment:
example: '17502.63'
type: string
description: Total amount paid by taker (price * qty + fees)
nullable: true
maker_total_receipt:
example: '17496.50'
type: string
description: Total amount received by maker (price * qty - rebate)
nullable: true
GetOrderbookResponse:
type: object
properties:
base_decimals:
example: 8
type: integer
description: Base token decimal places
format: int32
nullable: true
base_token:
example: BTC
type: string
description: Base token symbol
nullable: true
data:
$ref: '#/components/schemas/OrderbookData'
event_type:
example: orderbook_snapshot
type: string
description: Event type identifier
nullable: true
symbol:
example: BTC/USDC
type: string
description: Trading pair symbol
nullable: true
trading_pair_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Trading pair UUID
format: uuid
nullable: true
quote_decimals:
example: 6
type: integer
description: Quote token decimal places
format: int32
nullable: true
quote_token:
example: USDC
type: string
description: Quote token symbol
nullable: true
sequence_number:
example: 12345
type: integer
description: Orderbook sequence number
format: uint32
nullable: true
timestamp:
example: 2023-11-13T10:30:00Z
type: string
description: Snapshot timestamp
nullable: true
trading_mode:
example: Spot
type: string
description: Trading mode
nullable: true
description: Orderbook snapshot with token metadata and sequence number.
GetPortfolioChartResponse:
type: object
properties:
metric:
example: pnl
type: string
description: Metric used for this query
nullable: true
period:
example: 30d
type: string
description: Period used for this query
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/ChartDataPoint'
nullable: true
GetPortfolioStatsResponse:
type: object
properties:
period:
example: 30d
type: string
description: Period used for this query
nullable: true
volume:
example: '231.81'
type: string
description: Total trade volume (sum of quote_volume)
nullable: true
total_trades:
nullable: true
type: string
description: Number of trades in period
total_orders:
nullable: true
type: string
description: Number of orders in period
fees_paid:
example: '0.12'
type: string
description: Total fees paid by user
nullable: true
pnl:
example: '-0.01'
type: string
description: Profit and loss (CREDIT - DEBIT from trade ledger entries)
nullable: true
total_equity:
example: '280.93'
type: string
description: Total equity (sum of all balances)
nullable: true
spot_equity:
example: '280.93'
type: string
description: Spot account equity
nullable: true
perps_equity:
example: '0.00'
type: string
description: Perpetuals account equity
nullable: true
win_loss_ratio:
example: 0.65
type: number
description: Ratio of profitable trades to total trades
format: double
nullable: true
max_drawdown:
example: '0.00'
type: string
description: Maximum peak-to-trough drawdown on running PnL
nullable: true
GetProfileResponse:
type: object
properties:
id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: User UUID
format: uuid
nullable: true
address:
maxLength: 42
type: string
description: Wallet address
nullable: true
pattern: ^0x[0-9a-fA-F]{40}$
minLength: 42
username:
example: trader123
type: string
description: Display username
nullable: true
account_type:
example: master
type: string
description: 'Account type: master or sub'
nullable: true
can_withdraw:
example: true
type: boolean
description: Whether the user is allowed to withdraw
nullable: true
created_at:
example: 2023-11-13T10:30:00Z
type: string
description: Account creation timestamp (ISO 8601)
nullable: true
maker_fee_bps:
example: -1
type: integer
description: Base maker fee in basis points from active trading pair
format: int32
nullable: true
taker_fee_bps:
example: 5
type: integer
description: Base taker fee in basis points from active trading pair
format: int32
nullable: true
application_taker_fee_bps:
example: 0
type: integer
description: Additional taker fee in basis points from application
format: int32
nullable: true
application_maker_fee_bps:
example: 0
type: integer
description: Additional maker fee in basis points from application
format: int32
nullable: true
GetTradeByIdResponse:
type: object
properties:
trade:
$ref: '#/components/schemas/PublicTrade'
description: A single trade.
GetTradesResponse:
type: object
properties:
trades:
type: array
items:
$ref: '#/components/schemas/PublicTrade'
nullable: true
page:
example: 1
type: integer
description: Current page number
format: uint32
nullable: true
page_size:
example: 25
type: integer
description: Maximum number of trades returned
format: uint32
nullable: true
description: Recent trades for a trading pair.
GetTradingPairResponse:
type: object
properties:
trading_pair:
$ref: '#/components/schemas/TradingPairData'
description: Single trading pair details.
GetUserTradesResponse:
type: object
properties:
trades:
type: array
items:
$ref: '#/components/schemas/UserTrade'
nullable: true
page:
nullable: true
type: string
description: Current page number
page_size:
nullable: true
type: string
description: Items per page
total:
nullable: true
type: string
description: Total number of trades
total_pages:
nullable: true
type: string
description: Total number of pages
LedgerMovement:
type: object
properties:
id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Movement UUID
format: uuid
nullable: true
entry_type:
example: CREDIT
type: string
description: 'Ledger entry type: CREDIT, DEBIT, LOCK, UNLOCK, or FEE'
nullable: true
transaction_type:
example: DEPOSIT
type: string
description: 'Transaction type: DEPOSIT, WITHDRAWAL, TRADE, or FEE'
nullable: true
amount:
example: '100.50'
type: string
description: Human-readable amount in token units
nullable: true
token:
nullable: true
type: string
description: Token contract address
balance_before:
example: '900.00'
type: string
description: Available balance before this movement
nullable: true
balance_after:
example: '1000.50'
type: string
description: Available balance after this movement
nullable: true
locked_before:
example: '50.00'
type: string
description: Locked balance before this movement
nullable: true
locked_after:
example: '75.00'
type: string
description: Locked balance after this movement
nullable: true
reference_id:
example: ref_123456
type: string
description: ID of the related entity (order, trade, etc.)
nullable: true
reference_type:
example: deposit
type: string
description: Type of the referenced entity
nullable: true
description:
example: USDC deposit
type: string
description: Human-readable description of the movement
nullable: true
tx_hash:
nullable: true
type: string
description: On-chain transaction hash (if applicable)
block_number:
nullable: true
type: string
description: Block number of the on-chain transaction
created_at:
example: 2023-11-13T10:30:00Z
type: string
description: Movement timestamp (ISO 8601)
nullable: true
symbol:
example: USDC
type: string
description: Token symbol
nullable: true
decimals:
example: 6
type: integer
description: Token decimal places
format: int32
nullable: true
amount_raw:
example: '100500000'
type: string
description: Raw amount in smallest token unit (no decimals)
nullable: true
balance_before_raw:
example: '900000000'
type: string
description: Raw available balance before this movement
nullable: true
balance_after_raw:
example: '1000500000'
type: string
description: Raw available balance after this movement
nullable: true
locked_before_raw:
example: '50000000'
type: string
description: Raw locked balance before this movement
nullable: true
locked_after_raw:
example: '75000000'
type: string
description: Raw locked balance after this movement
nullable: true
asset_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Asset UUID
format: uuid
nullable: true
user_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: User UUID who owns this movement
format: uuid
nullable: true
balance_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Balance UUID this movement affects
format: uuid
nullable: true
ListAppBalancesResponse:
type: object
properties:
balances:
type: array
items:
$ref: '#/components/schemas/ApplicationBalance'
nullable: true
total:
example: 50
type: integer
description: Total matching balances
format: uint32
nullable: true
page:
example: 1
type: integer
description: Current page number
format: uint32
nullable: true
page_size:
example: 20
type: integer
description: Items per page
format: uint32
nullable: true
total_pages:
example: 3
type: integer
description: Total number of pages
format: uint32
nullable: true
ListAppMovementsResponse:
type: object
properties:
movements:
type: array
items:
$ref: '#/components/schemas/ApplicationMovement'
nullable: true
total:
example: 150
type: integer
description: Total matching movements
format: uint32
nullable: true
page:
example: 1
type: integer
description: Current page number
format: uint32
nullable: true
page_size:
example: 20
type: integer
description: Items per page
format: uint32
nullable: true
total_pages:
example: 8
type: integer
description: Total number of pages
format: uint32
nullable: true
ListAppOrdersResponse:
type: object
properties:
orders:
type: array
items:
$ref: '#/components/schemas/ApplicationOrder'
nullable: true
total:
example: 150
type: integer
description: Total matching orders
format: uint32
nullable: true
page:
example: 1
type: integer
description: Current page number
format: uint32
nullable: true
page_size:
example: 20
type: integer
description: Items per page
format: uint32
nullable: true
total_pages:
example: 8
type: integer
description: Total number of pages
format: uint32
nullable: true
ListAppUsersResponse:
type: object
properties:
users:
type: array
items:
$ref: '#/components/schemas/AppUser'
nullable: true
total:
example: 50
type: integer
description: Total number of users
format: uint32
nullable: true
page:
example: 1
type: integer
description: Current page number
format: uint32
nullable: true
page_size:
example: 20
type: integer
description: Items per page
format: uint32
nullable: true
total_pages:
example: 3
type: integer
description: Total number of pages
format: uint32
nullable: true
ListOrdersResponse:
type: object
properties:
orders:
type: array
items:
$ref: '#/components/schemas/GetOrderResponse'
nullable: true
total:
example: 150
type: integer
description: Total number of orders matching the filter
format: uint32
nullable: true
page:
example: 1
type: integer
description: Current page number
format: uint32
nullable: true
page_size:
example: 20
type: integer
description: Items per page
format: uint32
nullable: true
total_pages:
example: 8
type: integer
description: Total number of pages
format: uint32
nullable: true
ListSubAccountsResponse:
type: object
properties:
sub_accounts:
type: array
items:
$ref: '#/components/schemas/SubAccount'
nullable: true
total:
example: 0
type: integer
description: Total number of sub-accounts
format: uint32
nullable: true
ListTradingPairsResponse:
type: object
properties:
trading_pairs:
type: array
items:
$ref: '#/components/schemas/TradingPairData'
nullable: true
page:
example: 1
type: integer
description: Current page number
format: uint32
nullable: true
page_size:
example: 20
type: integer
description: Items per page
format: uint32
nullable: true
total:
example: 50
type: integer
description: Total number of trading pairs
format: uint32
nullable: true
total_pages:
example: 3
type: integer
description: Total number of pages
format: uint32
nullable: true
description: Paginated list of trading pairs.
MatchResult:
type: object
properties:
trades_count:
example: 2
type: integer
description: Number of trades generated by this order
format: int32
nullable: true
total_filled:
example: '0.2'
type: string
description: Total quantity filled
nullable: true
remaining_quantity:
example: '0.3'
type: string
description: Remaining unfilled quantity
nullable: true
average_fill_price:
example: '35100.00'
type: string
description: Volume-weighted average fill price
nullable: true
order_status:
example: PARTIALLY_FILLED
type: string
description: Resulting order status after matching
nullable: true
actual_slippage_bps:
example: 15
type: integer
description: Actual slippage incurred in basis points
format: int32
nullable: true
max_slippage_bps:
example: 50
type: integer
description: Maximum slippage tolerance that was set
format: int32
nullable: true
execution_price_range:
$ref: '#/components/schemas/ExecutionPriceRange'
MintTokensResponse:
type: object
properties:
minted:
type: array
items:
$ref: '#/components/schemas/MintedToken'
nullable: true
failed:
type: array
items:
$ref: '#/components/schemas/FailedMint'
nullable: true
remaining_requests_24h:
example: 4
type: integer
description: Remaining faucet requests in next 24h
format: uint32
nullable: true
MintedToken:
type: object
properties:
asset_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Asset UUID
nullable: true
format: uuid
symbol:
example: USDC
type: string
description: Token symbol
nullable: true
amount:
example: '10000.00'
type: string
description: Amount minted in token units
nullable: true
tx_hash:
nullable: true
type: string
description: On-chain transaction hash
OrderbookData:
type: object
properties:
bids:
type: array
items:
$ref: '#/components/schemas/PriceLevel'
nullable: true
asks:
type: array
items:
$ref: '#/components/schemas/PriceLevel'
nullable: true
best_bid:
example: '34900.00'
type: string
description: Highest bid price
nullable: true
best_ask:
example: '35100.00'
type: string
description: Lowest ask price
nullable: true
bid_volume:
example: '15.5'
type: string
description: Total bid-side volume
nullable: true
ask_volume:
example: '12.3'
type: string
description: Total ask-side volume
nullable: true
price_change:
$ref: '#/components/schemas/PriceChange'
PriceChange:
type: object
properties:
price_24h_ago:
example: '34500.00'
type: string
description: Price 24 hours ago
nullable: true
price_change_24h:
example: '500.00'
type: string
description: Absolute price change in last 24 hours
nullable: true
price_change_percent_24h:
example: '1.45'
type: string
description: Percentage price change in last 24 hours
nullable: true
PriceLevel:
type: object
properties:
price:
example: '35000.00'
type: string
description: Price at this level
nullable: true
quantity:
example: '1.5'
type: string
description: Total quantity at this price level
nullable: true
order_count:
example: 3
type: integer
description: Number of orders at this price level
format: uint32
nullable: true
PublicHealthCheckResponse:
type: object
properties:
status:
example: healthy
type: string
description: 'Health status: healthy or unhealthy'
nullable: true
service:
example: api-gateway
type: string
description: Service name
nullable: true
version:
example: 0.1.0
type: string
description: Service version
nullable: true
timestamp:
example: 1699872600
type: integer
description: Current server timestamp (Unix epoch seconds)
format: int32
nullable: true
PublicTrade:
type: object
properties:
trade_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Trade UUID
format: uuid
nullable: true
trading_pair_id:
example: 456e7890-e12b-12d3-a456-426614174000
type: string
description: Trading pair UUID
format: uuid
nullable: true
price:
example: '35000.00'
type: string
description: Execution price
nullable: true
quantity:
example: '0.5'
type: string
description: Traded quantity in base token
nullable: true
side:
example: BUY
type: string
description: 'Taker side: BUY or SELL'
nullable: true
trading_mode:
example: SPOT
type: string
description: 'Trading mode: SPOT or MARGIN'
nullable: true
executed_at:
example: 2023-11-13T10:30:00Z
type: string
description: Trade execution timestamp (ISO 8601)
nullable: true
RefreshRequest:
required:
- refresh_token
type: object
properties:
refresh_token:
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
type: string
description: Valid refresh token from a previous authentication
additionalProperties: false
RefreshResponse:
type: object
properties:
access_token:
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
type: string
description: New JWT access token
nullable: true
refresh_token:
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
type: string
description: New JWT refresh token
nullable: true
expires_at:
example: 1699876543
type: integer
description: Unix timestamp when access token expires
format: int32
nullable: true
ReplaceOrderRequest:
type: object
properties:
use_master_balance:
example: false
type: boolean
description: Use master account balance for sub-account orders
nullable: true
price:
example: '35500.00'
type: string
description: New limit price (if changing)
nullable: true
quantity:
example: '0.7'
type: string
description: New quantity (if changing)
nullable: true
additionalProperties: false
ReplaceOrderResponse:
type: object
properties:
order_id:
example: 987e6543-e21b-12d3-a456-426614174000
type: string
description: New replacement order UUID
format: uuid
nullable: true
status:
example: SUCCESS
type: string
description: 'Result status: SUCCESS or FAILED'
nullable: true
message:
example: Order replaced successfully
type: string
description: Human-readable status message
nullable: true
original_order_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: UUID of the original cancelled order
format: uuid
nullable: true
updated_fields:
$ref: '#/components/schemas/UpdatedFields'
match_result:
$ref: '#/components/schemas/MatchResult'
RevokeRequest:
type: object
properties: {}
additionalProperties: false
RevokeResponse:
type: object
properties:
message:
example: Session revoked successfully
type: string
description: Human-readable status message
nullable: true
SimulateFeesResponse:
type: object
properties:
notional:
example: '20000.00'
type: string
description: Notional value (price x quantity)
nullable: true
monaco_taker_fee:
example: '20.00'
type: string
description: Monaco protocol taker fee in quote token
nullable: true
monaco_maker_rebate:
example: '-5.00'
type: string
description: Monaco maker rebate in quote token (negative)
nullable: true
application_taker_fee:
example: '10.00'
type: string
description: Application-specific taker fee in quote token
nullable: true
total_taker_fees:
example: '30.00'
type: string
description: Total taker fees (monaco + application)
nullable: true
taker_total_payment:
example: '20030.00'
type: string
description: Total amount paid by taker (notional + fees)
nullable: true
maker_total_receipt:
example: '19995.00'
type: string
description: Total amount received by maker (notional - rebate)
nullable: true
buy_order_lock_amount:
example: '20030.00'
type: string
description: Amount locked for buy orders. For MARKET orders, includes slippage buffer.
nullable: true
monaco_taker_fee_bps:
example: 10
type: integer
description: Monaco taker fee rate in basis points
format: int32
nullable: true
monaco_maker_rebate_bps:
example: -2
type: integer
description: Monaco maker rebate rate in bps (negative)
format: int32
nullable: true
application_taker_fee_bps:
example: 5
type: integer
description: Application taker fee rate in basis points
format: int32
nullable: true
application_name:
example: Monaco Trading Frontend
type: string
description: Application display name
nullable: true
max_quantity:
example: '99.95'
type: string
description: Maximum quantity affordable at the given price, accounting for fees and slippage. Powers the 100% range input on the FE.
nullable: true
max_quantity_raw:
example: '99950000000000000000'
type: string
description: Maximum quantity in RAW (smallest unit) format
nullable: true
slippage_tolerance_bps:
example: 500
type: integer
description: Slippage tolerance used in the calculation (echoed back)
format: int32
nullable: true
SubAccount:
type: object
properties:
id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Sub-account UUID
format: uuid
nullable: true
address:
maxLength: 42
type: string
description: Sub-account wallet address
nullable: true
pattern: ^0x[0-9a-fA-F]{40}$
minLength: 42
username:
example: sub_trader_1
type: string
description: Sub-account display username
nullable: true
can_withdraw:
example: false
type: boolean
description: Whether the sub-account is allowed to withdraw
nullable: true
created_at:
example: 2023-11-13T10:30:00Z
type: string
description: Account creation timestamp (ISO 8601)
nullable: true
balances:
type: array
items:
$ref: '#/components/schemas/AccountBalance'
nullable: true
SubAccountLimit:
type: object
properties:
id:
example: 987e6543-e21b-12d3-a456-426614174000
type: string
description: Limit UUID
format: uuid
nullable: true
sub_account_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Sub-account UUID this limit applies to
format: uuid
nullable: true
token:
nullable: true
type: string
description: Token contract address
daily_limit:
example: '1000.00'
type: string
description: Maximum daily spending limit in token units
nullable: true
used_today:
example: '250.50'
type: string
description: Amount used today against the limit
nullable: true
created_at:
example: 2023-11-13T10:30:00Z
type: string
description: Limit creation timestamp (ISO 8601)
nullable: true
updated_at:
example: 2023-11-13T10:30:00Z
type: string
description: Last update timestamp (ISO 8601)
nullable: true
master_account_id:
example: 123e4567-e89b-12d3-a456-426614174001
type: string
description: Master account UUID that owns this sub-account
format: uuid
nullable: true
max_amount:
example: '1500.00'
type: string
description: Maximum amount allowed in token units
nullable: true
last_reset_at:
example: 2023-11-13T00:00:00Z
type: string
description: Last reset timestamp for the daily limit (ISO 8601)
nullable: true
is_active:
example: true
type: boolean
description: Whether the limit is active
nullable: true
SubmitWhitelistRequest:
required:
- wallet_address
- email
type: object
properties:
wallet_address:
description: Applicant wallet address
maxLength: 42
minLength: 42
pattern: ^0x[0-9a-fA-F]{40}$
type: string
email:
example: user@example.com
minLength: 1
type: string
description: Applicant email address
format: email
twitter_username:
example: monaco_user
maxLength: 15
minLength: 1
pattern: ^[A-Za-z0-9_]{1,15}$
type: string
description: Applicant Twitter/X username
nullable: true
telegram_username:
example: monaco_user
maxLength: 32
minLength: 5
pattern: ^[a-zA-Z0-9_]{5,32}$
type: string
description: Applicant Telegram username
nullable: true
additionalProperties: false
SubmitWhitelistResponse:
type: object
properties:
message:
example: Your whitelist application has been submitted successfully! We'll review it and get back to you soon.
type: string
description: Human-readable status message
nullable: true
user_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Created user UUID (pending approval)
nullable: true
format: uuid
TradingPairData:
type: object
properties:
base_asset_id:
example: 456e7890-e12b-12d3-a456-426614174000
type: string
description: Base asset UUID
format: uuid
nullable: true
base_decimals:
example: 8
type: integer
description: Base token decimal places
format: int32
nullable: true
base_icon_url:
example: https://cdn.0xmonaco.com/assets/btc.svg
type: string
description: Base token icon URL
nullable: true
base_token:
example: BTC
type: string
description: Base token symbol
nullable: true
base_token_contract:
nullable: true
type: string
description: Base token contract address
id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Trading pair UUID
format: uuid
nullable: true
is_active:
example: true
type: boolean
description: Pair active
nullable: true
maker_fee_bps:
example: -2
type: integer
description: Maker fee in bps (negative = rebate)
format: int32
nullable: true
market_type:
example: SPOT
type: string
description: 'Market type: SPOT or MARGIN'
nullable: true
max_order_size:
example: '100.0'
type: string
description: Maximum order size in base token
nullable: true
min_order_size:
example: '0.0001'
type: string
description: Minimum order size in base token
nullable: true
quote_asset_id:
example: 789e0123-e45b-12d3-a456-426614174000
type: string
description: Quote asset UUID
format: uuid
nullable: true
quote_decimals:
example: 6
type: integer
description: Quote token decimal places
format: int32
nullable: true
quote_icon_url:
example: https://cdn.0xmonaco.com/assets/usdc.svg
type: string
description: Quote token icon URL
nullable: true
quote_token:
example: USDC
type: string
description: Quote token symbol
nullable: true
quote_token_contract:
nullable: true
type: string
description: Quote token contract address
symbol:
example: BTC/USDC
type: string
description: Trading pair symbol
nullable: true
taker_fee_bps:
example: 10
type: integer
description: Taker fee (bps)
format: int32
nullable: true
tick_size:
example: '0.01'
type: string
description: Minimum price increment
nullable: true
description: Trading pair configuration including tokens, fees, and order limits.
UpdateLimitRequest:
type: object
properties:
sub_account_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Sub-account UUID
format: uuid
nullable: true
asset_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Asset UUID
format: uuid
nullable: true
max_amount:
example: '1500.00'
minLength: 1
pattern: ^-?[0-9]{1,28}(\.[0-9]{1,18})?$
type: string
description: New maximum amount allowed in token units
nullable: true
daily_limit:
example: '500.00'
minLength: 1
pattern: ^-?[0-9]{1,28}(\.[0-9]{1,18})?$
type: string
description: New maximum daily spending limit in token units
nullable: true
is_active:
example: true
type: boolean
description: Whether the limit is active
nullable: true
additionalProperties: false
UpdateLimitResponse:
type: object
properties:
limit:
$ref: '#/components/schemas/SubAccountLimit'
UpdatedFields:
type: object
properties:
price:
example: '35500.00'
type: string
description: New price (if changed)
nullable: true
quantity:
example: '0.7'
type: string
description: New quantity (if changed)
nullable: true
UserInfo:
type: object
properties:
id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: User UUID
format: uuid
nullable: true
address:
maxLength: 42
type: string
description: Wallet address
nullable: true
pattern: ^0x[0-9a-fA-F]{40}$
minLength: 42
username:
example: trader123
type: string
description: Display username
nullable: true
UserTrade:
type: object
properties:
trade_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Trade UUID
format: uuid
nullable: true
trading_pair_id:
example: 456e7890-e12b-12d3-a456-426614174000
type: string
description: Trading pair UUID
format: uuid
nullable: true
price:
example: '35000.00'
type: string
description: Execution price
nullable: true
quantity:
example: '0.5'
type: string
description: Traded quantity
nullable: true
quote_volume:
example: '17500.00'
type: string
description: Quote volume (price * quantity)
nullable: true
side:
example: Buy
type: string
description: 'User''s side: Buy or Sell'
nullable: true
fee:
example: '0.875'
type: string
description: Fee paid by this user for this trade
nullable: true
fee_token:
nullable: true
type: string
description: Token address of the fee
executed_at:
example: 2023-11-13T10:30:00Z
type: string
description: Trade execution timestamp (ISO 8601)
nullable: true
VerifyRequest:
required:
- address
- signature
- nonce
type: object
properties:
address:
description: Ethereum wallet address
maxLength: 42
minLength: 42
pattern: ^0x[0-9a-fA-F]{40}$
type: string
signature:
description: Signed message
minLength: 1
type: string
nonce:
example: abc123def456
minLength: 1
type: string
description: Challenge nonce
client_id:
example: monaco-frontend
type: string
description: Optional application identifier
nullable: true
chain_id:
nullable: true
type: string
description: Optional chain ID supplied by SDK clients
additionalProperties: false
VerifyResponse:
type: object
properties:
access_token:
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
type: string
description: JWT access token for API requests
nullable: true
refresh_token:
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
type: string
description: JWT refresh token for obtaining new access tokens
nullable: true
expires_at:
example: 1699876543
type: integer
description: Unix timestamp when access token expires
format: int32
nullable: true
user:
$ref: '#/components/schemas/UserInfo'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
apiKey:
type: apiKey
name: x-server-key
in: header
tags:
- name: AccountsService
- name: ApplicationsService
- name: AuthService
- name: FaucetService
- name: FeesService
- name: HealthService
- name: MarketService
- name: OrderbookService
- name: OrdersService
- name: TradesService
- name: WhitelistService