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://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:
- monacoSignature: []
/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:
- monacoSignature: []
/api/v1/accounts/funding-payments:
get:
tags:
- AccountsService
- Accounts
summary: List funding payments
description: |-
List funding payment history.
Get the current user's private funding payment history with pagination and
optional filters by market, margin account, and position.
operationId: list_funding_payments
parameters:
- name: trading_pair_id
in: query
schema:
type: string
minLength: 1
format: uuid
description: Trading pair identifier (UUID)
- name: position_id
in: query
schema:
type: string
- name: margin_account_id
in: query
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: 20
description: Items per page (max 100)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListFundingPaymentsResponse'
'400':
description: Invalid request
'401':
description: Authentication required
'500':
description: Internal server error
security:
- monacoSignature: []
/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:
- monacoSignature: []
/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:
- monacoSignature: []
/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:
- monacoSignature: []
/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:
- monacoSignature: []
/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:
- monacoSignature: []
/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:
- monacoSignature: []
/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:
- monacoSignature: []
/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:
- monacoSignature: []
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:
- monacoSignature: []
/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:
- monacoSignature: []
/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:
- monacoSignature: []
/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/stats:
get:
tags:
- ApplicationsService
- Applications (Backend)
summary: Get application stats
description: |-
Get application stats.
Returns aggregate volume and fee stats for this application. Stats are
scoped to trades where the application's users were the taker. Requires
backend authentication via secret key.
operationId: get_application_stats
parameters:
- name: since
in: query
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetAppStatsResponse'
'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 session expiry
description: |-
Refresh session expiry.
Extends the expiration of the current session. The request must be signed
by the session private key (standard X-Monaco-* headers); no body is
required.
operationId: refresh_session
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RefreshRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RefreshResponse'
'401':
description: Missing, invalid, or expired session signature
'404':
description: Session not found
'500':
description: Internal server error
security:
- monacoSignature: []
/api/v1/auth/revoke:
post:
tags:
- AuthService
- Auth
summary: Revoke current session
description: |-
Revoke current session.
Revoke the current authenticated session. The request must be signed by
the session private key (standard X-Monaco-* headers). The user will need
to authenticate again to obtain a new session.
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 session signature
'404':
description: Session not found
'500':
description: Internal server error
security:
- monacoSignature: []
/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.
Binds the caller-provided ed25519 session public key to the new session;
subsequent requests are signed with the matching private key.
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/delegated-agents:
get:
tags:
- DelegatedAgentsService
- DelegatedAgents
summary: List delegated agents
description: |-
List the calling owner's delegated agents.
Master accounts only. Returns every agent the calling account owns, each
with its policy.
operationId: list_delegated_agents
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListDelegatedAgentsResponse'
'401':
description: Authentication required
'403':
description: Only master accounts can list delegated agents
'500':
description: Internal server error
security:
- monacoSignature: []
post:
tags:
- DelegatedAgentsService
- DelegatedAgents
summary: Upsert delegated agent
description: |-
Register or update a delegated agent.
Master accounts only. Creates (or updates, keyed on `agent_address`) a
delegation linking the calling owner to an agent wallet, together with the
policy that constrains what the agent may do on the owner's behalf.
operationId: upsert_delegated_agent
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertDelegatedAgentRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DelegatedAgent'
'400':
description: Invalid request
'401':
description: Authentication required
'403':
description: Only master accounts can manage delegated agents
'500':
description: Internal server error
security:
- monacoSignature: []
/api/v1/delegated-agents/owners:
get:
tags:
- DelegatedAgentsService
- DelegatedAgents
summary: List delegating owners
description: |-
List the owners that have delegated to the calling agent.
Reverse lookup keyed on the caller's own wallet address: an agent that has
authenticated with its own session key can discover which owners it may act
on behalf of, and the `owner_user_id` to pass to `CreateDelegatedSession`.
Returns only active (non-revoked, non-expired) delegations.
operationId: list_delegated_agent_owners
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListDelegatedAgentOwnersResponse'
'401':
description: Authentication required
'500':
description: Internal server error
security:
- monacoSignature: []
/api/v1/delegated-agents/sessions:
post:
tags:
- DelegatedAgentsService
- DelegatedAgents
summary: Create delegated session
description: |-
Exchange the agent's session for an owner-scoped delegated session.
The agent authenticates with its own session key, then calls this with the
`owner_user_id` it wants to act for (discover it via
`ListDelegatedAgentOwners`) and a freshly generated session public key.
The new session acts as the owner but records the agent's address for
policy enforcement. Requires an active delegation for the (owner, agent)
pair.
operationId: create_delegated_session
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDelegatedSessionRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDelegatedSessionResponse'
'400':
description: Invalid request
'401':
description: Authentication required
'403':
description: No active delegation for owner
'500':
description: Internal server error
security:
- monacoSignature: []
/api/v1/delegated-agents/{delegated_agent_id}:
delete:
tags:
- DelegatedAgentsService
- DelegatedAgents
summary: Revoke delegated agent
description: |-
Revoke a delegated agent.
Master accounts only. Revokes the delegation identified by
`delegated_agent_id`. Existing delegated sessions are not invalidated; only
future session creation is blocked.
operationId: revoke_delegated_agent
parameters:
- name: delegated_agent_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RevokeDelegatedAgentResponse'
'400':
description: Invalid delegated_agent_id
'401':
description: Authentication required
'403':
description: Only master accounts can revoke delegated agents
'404':
description: Delegated agent not found
'500':
description: Internal server error
security:
- monacoSignature: []
/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:
- monacoSignature: []
/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:
- monacoSignature: []
/api/v1/margin/accounts:
get:
tags:
- MarginAccountsService
operationId: list_margin_accounts
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: state
in: query
schema:
type: string
- 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/ListMarginAccountsResponse'
/api/v1/margin/accounts/{margin_account_id}:
get:
tags:
- MarginAccountsService
operationId: get_margin_account_summary
parameters:
- name: margin_account_id
in: path
description: Margin account UUID for the current isolated bucket.
required: true
schema:
type: string
- name: trading_pair_id
in: query
description: Trading pair identifier (UUID)
schema:
type: string
minLength: 1
format: uuid
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetMarginAccountSummaryResponse'
/api/v1/margin/accounts/{margin_account_id}/collateral/transfer-in:
post:
tags:
- MarginAccountsService
operationId: transfer_collateral_to_margin_account
parameters:
- name: margin_account_id
in: path
description: Parent margin account UUID that receives collateral.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransferCollateralToMarginAccountRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TransferCollateralToMarginAccountResponse'
/api/v1/margin/accounts/{margin_account_id}/collateral/transfer-out:
post:
tags:
- MarginAccountsService
operationId: transfer_collateral_from_margin_account
parameters:
- name: margin_account_id
in: path
description: Parent margin account UUID that releases collateral.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransferCollateralFromMarginAccountRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TransferCollateralFromMarginAccountResponse'
/api/v1/margin/accounts/{margin_account_id}/movements:
get:
tags:
- MarginAccountsService
operationId: get_margin_account_movements
parameters:
- name: margin_account_id
in: path
description: Margin account UUID for the current isolated bucket.
required: true
schema:
type: string
- name: movement_type
in: query
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: 20
description: Items per page (max 100)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetMarginAccountMovementsResponse'
/api/v1/margin/accounts/{margin_account_id}/simulate-order-risk:
post:
tags:
- MarginAccountsService
operationId: simulate_order_risk
parameters:
- name: margin_account_id
in: path
description: Margin account UUID for the isolated bucket being simulated.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SimulateOrderRiskRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SimulateOrderRiskResponse'
/api/v1/margin/collateral/available:
get:
tags:
- MarginAccountsService
operationId: get_available_collateral
parameters:
- name: asset
in: query
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetAvailableCollateralResponse'
/api/v1/margin/parent-margin-account:
get:
tags:
- MarginAccountsService
operationId: get_parent_margin_account_summary
parameters:
- name: trading_pair_id
in: query
description: Trading pair identifier (UUID)
schema:
type: string
minLength: 1
format: uuid
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetMarginAccountSummaryResponse'
/api/v1/margin/parent-margin-account/collateral/transfer-in:
post:
tags:
- MarginAccountsService
operationId: transfer_collateral_to_parent_margin_account
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransferCollateralToParentMarginAccountRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TransferCollateralToMarginAccountResponse'
/api/v1/margin/parent-margin-account/collateral/transfer-out:
post:
tags:
- MarginAccountsService
operationId: transfer_collateral_from_parent_margin_account
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransferCollateralFromParentMarginAccountRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TransferCollateralFromMarginAccountResponse'
/api/v1/margin/parent-margin-account/movements:
get:
tags:
- MarginAccountsService
operationId: get_parent_margin_account_movements
parameters:
- name: movement_type
in: query
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: 20
description: Items per page (max 100)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetMarginAccountMovementsResponse'
/api/v1/margin/parent-margin-account/simulate-order-risk:
post:
tags:
- MarginAccountsService
operationId: simulate_parent_margin_order_risk
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SimulateParentMarginOrderRiskRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SimulateOrderRiskResponse'
/api/v1/margin/risk-buckets/collateral/transfer-in:
post:
tags:
- MarginAccountsService
operationId: transfer_collateral_to_risk_bucket
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransferCollateralToRiskBucketRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TransferCollateralToMarginAccountResponse'
/api/v1/margin/risk-buckets/simulate-order-risk:
post:
tags:
- MarginAccountsService
operationId: simulate_risk_bucket_order_risk
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SimulateRiskBucketOrderRiskRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SimulateOrderRiskResponse'
/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
- name: category
in: query
schema:
type: string
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}/funding:
get:
tags:
- MarketService
description: Funding state for a perp market.
operationId: get_funding_state
parameters:
- name: trading_pair_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetFundingStateResponse'
/api/v1/market/pairs/{trading_pair_id}/funding/history:
get:
tags:
- MarketService
description: Historical funding settlements for a perp market.
operationId: list_funding_history
parameters:
- name: trading_pair_id
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: 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/ListFundingHistoryResponse'
/api/v1/market/pairs/{trading_pair_id}/index-price:
get:
tags:
- MarketService
description: Current index/oracle price for a perp market.
operationId: get_index_price
parameters:
- name: trading_pair_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetIndexPriceResponse'
/api/v1/market/pairs/{trading_pair_id}/mark-price:
get:
tags:
- MarketService
description: Current mark price for a perp market.
operationId: get_mark_price
parameters:
- name: trading_pair_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetMarkPriceResponse'
/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/market/pairs/{trading_pair_id}/open-interest:
get:
tags:
- MarketService
- Market
summary: Open Interest
description: Open interest for a perp market.
operationId: get_open_interest
parameters:
- name: trading_pair_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetOpenInterestResponse'
'404':
description: Trading pair not found
'500':
description: Internal server error
/api/v1/market/pairs/{trading_pair_id}/perp/config:
get:
tags:
- MarketService
description: Perp market risk/config parameters.
operationId: get_perp_market_config
parameters:
- name: trading_pair_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetPerpMarketConfigResponse'
/api/v1/market/pairs/{trading_pair_id}/perp/summary:
get:
tags:
- MarketService
description: Perp market summary combining public candles, risk marks, funding, and open interest.
operationId: get_perp_market_summary
parameters:
- name: trading_pair_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetPerpMarketSummaryResponse'
/api/v1/market/screener:
get:
tags:
- MarketService
- Market
summary: Market Screener
description: |-
Market Screener
Single-call aggregate of per-pair market stats across all trading pairs.
Returns current price plus quote-volume and percent price change for
1h / 24h / 7d windows, and a 7-point UTC-day snapshot for sparkline
rendering. Window fields are independently null when a pair lacks
sufficient history. Results sorted by quote_volume_24h descending
(nulls last) and paginated.
operationId: get_screener
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: 50
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: is_active
in: query
schema:
type: boolean
- name: category
in: query
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetScreenerResponse'
'400':
description: Invalid query parameter (page, page_size, market_type)
'500':
description: Internal server error
/api/v1/market/stats:
get:
tags:
- MarketService
- Market
summary: Market Stats
description: |-
Market Stats
Exchange-wide life-to-date (since-inception) cumulative totals across all
trading pairs: total quote-token volume and total number of trades. No
auth required.
operationId: get_market_stats
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetMarketStatsResponse'
'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: trading_mode
in: query
schema:
type: string
enum:
- SPOT
- MARGIN
minLength: 1
description: Trading mode
- name: margin_account_id
in: query
schema:
type: string
- 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:
- monacoSignature: []
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:
- monacoSignature: []
/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:
- monacoSignature: []
/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:
- monacoSignature: []
/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:
- monacoSignature: []
/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:
- monacoSignature: []
/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:
- monacoSignature: []
/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:
- monacoSignature: []
/api/v1/orders/conditional:
get:
tags:
- OrdersService
description: List conditional TP/SL orders for the authenticated user.
operationId: list_conditional_orders
parameters:
- name: margin_account_id
in: query
schema:
type: string
- name: trading_pair_id
in: query
schema:
type: string
minLength: 1
format: uuid
description: Trading pair identifier (UUID)
- name: state
in: query
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: 20
description: Items per page (max 100)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListConditionalOrdersResponse'
/api/v1/orders/conditional/{conditional_order_id}:
delete:
tags:
- OrdersService
description: Cancel conditional TP/SL order.
operationId: cancel_conditional_order
parameters:
- name: conditional_order_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CancelConditionalOrderResponse'
/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:
- monacoSignature: []
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:
- monacoSignature: []
/api/v1/positions:
get:
tags:
- PositionsService
operationId: list_positions
parameters:
- name: margin_account_id
in: query
description: Optional isolated bucket filter.
schema:
type: string
- name: trading_pair_id
in: query
schema:
type: string
minLength: 1
format: uuid
description: Trading pair identifier (UUID)
- name: status
in: query
schema:
type: string
minLength: 1
description: Order status (single value or comma-separated list)
- 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/ListPositionsResponse'
/api/v1/positions/batch-close-all:
post:
tags:
- PositionsService
description: |-
Close all open positions in a single batch ("panic close").
Submits a MARKET reduce-only close for every open position owned by the
caller, optionally filtered to a single trading pair. Best-effort and
partial: each position closes independently and per-position failures are
reported in `results` rather than aborting the batch.
operationId: batch_close_all_positions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCloseAllRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCloseAllResponse'
/api/v1/positions/history:
get:
tags:
- PositionsService
operationId: list_position_history
parameters:
- name: position_id
in: query
schema:
type: string
- name: margin_account_id
in: query
schema:
type: string
- name: trading_pair_id
in: query
schema:
type: string
minLength: 1
format: uuid
description: Trading pair identifier (UUID)
- 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/ListPositionHistoryResponse'
/api/v1/positions/{position_id}:
get:
tags:
- PositionsService
operationId: get_position
parameters:
- name: position_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetPositionResponse'
/api/v1/positions/{position_id}/close:
post:
tags:
- PositionsService
operationId: close_position
parameters:
- name: position_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClosePositionRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ClosePositionResponse'
/api/v1/positions/{position_id}/margin/add:
post:
tags:
- PositionsService
operationId: add_position_margin
parameters:
- name: position_id
in: path
description: Position UUID for the isolated bucket being adjusted.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddPositionMarginRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AddPositionMarginResponse'
/api/v1/positions/{position_id}/margin/reduce:
post:
tags:
- PositionsService
operationId: reduce_position_margin
parameters:
- name: position_id
in: path
description: Position UUID for the isolated bucket being adjusted.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReducePositionMarginRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReducePositionMarginResponse'
/api/v1/positions/{position_id}/risk:
get:
tags:
- PositionsService
operationId: get_position_risk
parameters:
- name: position_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetPositionRiskResponse'
/api/v1/positions/{position_id}/tp-sl:
post:
tags:
- PositionsService
operationId: attach_position_tp_sl
parameters:
- name: position_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AttachPositionTpSlRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AttachPositionTpSlResponse'
/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
/api/v1/withdrawals:
post:
tags:
- WithdrawalsService
- Withdrawals
summary: Initiate withdrawal
description: |-
Initiate a withdrawal.
Master accounts with the withdraw permission only. Routes through the
matching engine to debit the balance and allocate a `withdrawal_index`,
then returns it plus the target vault address. The `calldata` field is
empty: `executeWithdrawal` requires the merkle proof, which only exists
after the withdrawal's root is confirmed on-chain. Poll GetWithdrawal to
obtain the calldata once it is ready.
operationId: initiate_withdrawal
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateWithdrawalRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Withdrawal'
'400':
description: Invalid request (bad amount, address, or asset)
'401':
description: Authentication required
'403':
description: Caller lacks the withdraw permission
'404':
description: Asset not found
'500':
description: Internal server error
'503':
description: Matching engine unavailable
security:
- monacoSignature: []
/api/v1/withdrawals/{withdrawal_index}:
get:
tags:
- WithdrawalsService
- Withdrawals
summary: Get withdrawal
description: |-
Fetch a withdrawal's executable calldata by index.
Public lookup — no auth. Returns the vault address and ABI-encoded
`executeWithdrawal(...)` calldata for a previously-initiated
`withdrawal_index`. The calldata is bound to the fixed
(index, metadata, owner, destination, token, amount) tuple persisted for
the withdrawal, so re-fetching it cannot redirect funds. Returns 409 while
the withdrawal's root has not been confirmed on-chain yet (proof not
available) — clients poll this endpoint until it succeeds.
operationId: get_withdrawal
parameters:
- name: withdrawal_index
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Withdrawal'
'404':
description: Withdrawal not found (may not be persisted yet)
'409':
description: Withdrawal not confirmed on-chain yet; retry shortly
'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
total_balance_raw:
example: '1050750000'
type: string
description: Raw total balance (available + locked) in smallest token unit
nullable: true
AddPositionMarginRequest:
type: object
properties:
asset:
type: string
description: Collateral asset to move into the isolated bucket. USDC is the current v1 path.
nullable: true
amount:
type: string
nullable: true
AddPositionMarginResponse:
type: object
properties:
position_id:
type: string
nullable: true
margin_account_id:
type: string
description: Margin account UUID for the isolated bucket that was adjusted.
nullable: true
new_isolated_margin:
type: string
nullable: true
status:
type: string
nullable: true
message:
type: string
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
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
AttachPositionTpSlRequest:
type: object
properties:
stop_loss:
$ref: '#/components/schemas/TpSlLeg'
take_profit:
$ref: '#/components/schemas/TpSlLeg'
AttachPositionTpSlResponse:
type: object
properties:
position_id:
type: string
nullable: true
take_profit_order_id:
type: string
nullable: true
stop_loss_order_id:
type: string
nullable: true
status:
type: string
nullable: true
message:
type: string
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'
BatchCloseAllRequest:
type: object
properties:
trading_pair_id:
type: string
description: |-
Optional trading-pair filter. When set, only open positions on this
trading pair are closed; otherwise every open position is closed.
nullable: true
format: uuid
slippage_tolerance_bps:
type: integer
description: Optional slippage tolerance (basis points) applied to each MARKET close.
format: int32
nullable: true
BatchCloseAllResponse:
type: object
properties:
total_requested:
type: integer
description: Number of open positions the batch attempted to close.
format: int32
nullable: true
total_closed:
type: integer
description: |-
Number of positions whose close order was accepted by the matching engine
(SUCCESS, PARTIAL, or PENDING).
format: int32
nullable: true
total_failed:
type: integer
description: |-
Number of positions whose close failed (validation, lookup, or a rejected
close order).
format: int32
nullable: true
results:
type: array
items:
$ref: '#/components/schemas/BatchCloseResult'
nullable: true
BatchCloseError:
type: object
properties:
code:
type: string
description: |-
Machine-readable error code (e.g. POSITION_NOT_FOUND, INVALID_REQUEST,
MATCHING_ENGINE_ERROR).
nullable: true
message:
type: string
description: Human-readable error message.
nullable: true
BatchCloseResult:
type: object
properties:
position_id:
type: string
description: Position UUID this result is for.
nullable: true
close_order_id:
type: string
description: Close order UUID. Present when the close order was accepted.
nullable: true
status:
type: string
description: 'Close outcome: SUCCESS, PARTIAL, or PENDING. Present when accepted.'
nullable: true
submitted_quantity:
type: string
description: Quantity submitted on the close order. Present when accepted.
nullable: true
error:
allOf:
- $ref: '#/components/schemas/BatchCloseError'
description: Failure detail. Present when this position could not be closed.
nullable: true
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
margin_account_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Margin account UUID for margin orders
format: uuid
nullable: true
risk_bucket_id:
example: 123e4567-e89b-12d3-a456-426614174001
type: string
description: Existing isolated risk bucket UUID for risk-bucket-scoped margin orders
format: uuid
nullable: true
risk_bucket_collateral:
example: '1000'
type: string
description: Decimal collateral to allocate into a new isolated risk bucket. When provided, the API creates the bucket ID and matching-engine persists the bucket through the durable log.
nullable: true
position_side:
example: LONG
enum:
- LONG
- SHORT
- NONE
type: string
description: 'Position side for margin orders: LONG, SHORT, or NONE'
nullable: true
leverage:
example: '5'
type: string
description: Leverage multiplier as decimal string for margin orders
nullable: true
reduce_only:
example: false
type: boolean
description: Whether the margin order is reduce-only
nullable: true
strategy_key:
example: my-strategy
type: string
description: Strategy key used to group risk buckets for delegated/margin orders
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'
CancelConditionalOrderResponse:
type: object
properties:
conditional_order_id:
type: string
description: Conditional order UUID
format: uuid
nullable: true
status:
example: SUCCESS
type: string
description: Result status
nullable: true
message:
type: string
description: Human-readable status message
nullable: true
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
- session_public_key
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
session_public_key:
example: 3b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29
maxLength: 64
minLength: 64
pattern: ^[0-9a-f]{64}$
type: string
description: Lowercase hex (64 chars) ed25519 public key generated locally by the SDK. The returned challenge message will embed this key so the wallet's signature binds it; the same value must be submitted to /api/v1/auth/verify.
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
ClosePositionRequest:
type: object
properties:
quantity:
type: string
nullable: true
close_type:
type: string
nullable: true
limit_price:
type: string
nullable: true
slippage_tolerance_bps:
type: integer
format: int32
nullable: true
ClosePositionResponse:
type: object
properties:
close_order_id:
type: string
nullable: true
status:
type: string
nullable: true
message:
type: string
nullable: true
submitted_quantity:
type: string
nullable: true
ConditionalOrder:
type: object
properties:
conditional_order_id:
type: string
nullable: true
trading_pair_id:
type: string
nullable: true
format: uuid
margin_account_id:
type: string
nullable: true
position_id:
type: string
nullable: true
linked_group_id:
type: string
nullable: true
condition_type:
type: string
nullable: true
trigger_source:
type: string
nullable: true
trigger_price:
type: string
nullable: true
side:
type: string
nullable: true
position_side:
type: string
nullable: true
order_type:
type: string
nullable: true
limit_price:
type: string
nullable: true
quantity:
type: string
nullable: true
slippage_tolerance_bps:
type: integer
format: int32
nullable: true
reduce_only:
type: boolean
nullable: true
time_in_force:
type: string
nullable: true
state:
type: string
nullable: true
triggered_order_id:
type: string
nullable: true
triggered_at:
type: string
nullable: true
cancelled_at:
type: string
nullable: true
expires_at:
type: string
nullable: true
failure_reason:
type: string
nullable: true
created_at:
type: string
nullable: true
updated_at:
type: string
nullable: true
parent_order_id:
type: string
nullable: true
association_type:
type: string
nullable: true
activated_at:
type: string
nullable: true
CreateDelegatedSessionRequest:
type: object
properties:
owner_user_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Owner account UUID to act on behalf of (discover via ListDelegatedAgentOwners)
format: uuid
nullable: true
session_public_key:
type: string
description: Lowercase-hex (64 chars) ed25519 public key the agent generated for this delegated session. Subsequent requests acting on the owner's behalf are signed with the matching private key.
nullable: true
CreateDelegatedSessionResponse:
type: object
properties:
expires_at:
nullable: true
type: string
description: Session expiry as a Unix timestamp (seconds)
delegation_id:
type: string
description: Delegation UUID for the active (owner, agent) pair
format: uuid
nullable: true
owner_user_id:
type: string
description: Owner account UUID the session acts on behalf of
format: uuid
nullable: true
agent_address:
type: string
description: Agent wallet address recorded on the session for policy enforcement
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
margin_account_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Margin account UUID for margin orders
format: uuid
nullable: true
risk_bucket_id:
example: 123e4567-e89b-12d3-a456-426614174001
type: string
description: Existing isolated risk bucket UUID for risk-bucket-scoped margin orders
format: uuid
nullable: true
risk_bucket_collateral:
example: '1000'
type: string
description: Decimal collateral to allocate into a new isolated risk bucket. When provided, the API creates the bucket ID and matching-engine persists the bucket through the durable log.
nullable: true
position_side:
example: LONG
enum:
- LONG
- SHORT
- NONE
type: string
description: 'Position side for margin orders: LONG, SHORT, or NONE'
nullable: true
leverage:
example: '5'
type: string
description: Leverage multiplier as decimal string for margin orders
nullable: true
reduce_only:
example: false
type: boolean
description: Whether the margin order is reduce-only
nullable: true
take_profit:
$ref: '#/components/schemas/ParentTpSlLeg'
stop_loss:
$ref: '#/components/schemas/ParentTpSlLeg'
strategy_key:
example: my-strategy
type: string
description: Strategy key used to group risk buckets for delegated/margin orders
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'
take_profit_order_id:
type: string
description: Created parent take-profit conditional order UUID, when requested
format: uuid
nullable: true
stop_loss_order_id:
type: string
description: Created parent stop-loss conditional order UUID, when requested
format: uuid
nullable: true
margin_account_id:
type: string
description: Resolved margin account UUID for margin orders
format: uuid
nullable: true
risk_bucket_id:
type: string
description: Resolved isolated risk bucket UUID for risk-bucket-scoped margin orders
format: uuid
nullable: true
strategy_key:
type: string
description: Client strategy key carried for compatibility
nullable: true
delegation_id:
type: string
description: Delegated agent UUID when submitted through a delegated session
format: uuid
nullable: true
DelegatedAgent:
type: object
properties:
id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Delegation UUID
format: uuid
nullable: true
owner_user_id:
type: string
description: Owner account UUID the agent acts on behalf of
format: uuid
nullable: true
agent_address:
nullable: true
type: string
description: Agent wallet address (EVM)
name:
type: string
description: Human-friendly label for the agent
nullable: true
is_active:
type: boolean
description: Whether the delegation is active
nullable: true
expires_at:
type: string
description: Delegation expiry timestamp (ISO 8601), if set
nullable: true
revoked_at:
type: string
description: Revocation timestamp (ISO 8601), if revoked
nullable: true
allowed_actions:
type: array
items:
type: string
minLength: 1
description: Actions the agent may perform
nullable: true
allowed_trading_pair_ids:
type: array
items:
type: string
minLength: 1
format: uuid
description: Trading pair UUIDs the agent may trade
nullable: true
allowed_margin_account_ids:
type: array
items:
type: string
minLength: 1
format: uuid
description: Margin account UUIDs the agent may trade against
nullable: true
allowed_order_types:
type: array
items:
type: string
minLength: 1
description: Permitted order types. Empty means unrestricted.
nullable: true
allowed_time_in_force:
type: array
items:
type: string
minLength: 1
description: Permitted time-in-force values. Empty means unrestricted.
nullable: true
max_leverage:
type: string
description: Maximum leverage (decimal string), if set
nullable: true
max_order_notional:
type: string
description: Maximum order notional (decimal string), if set
nullable: true
max_open_orders:
type: integer
description: Maximum concurrent open orders, if set
format: int32
nullable: true
DelegatedAgentOwner:
type: object
properties:
owner_user_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Owner account UUID to pass to CreateDelegatedSession
format: uuid
nullable: true
delegation_id:
type: string
description: Delegation UUID for the (owner, agent) pair
format: uuid
nullable: true
name:
type: string
description: Human-friendly label the owner gave this agent, if any
nullable: true
is_active:
type: boolean
description: Whether the delegation is active
nullable: true
expires_at:
type: string
description: Delegation expiry timestamp (ISO 8601), if set
nullable: true
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
FundingPaymentRecord:
type: object
properties:
id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Funding payment UUID
format: uuid
nullable: true
position_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Margin position UUID
format: uuid
nullable: true
margin_account_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Margin account UUID
format: uuid
nullable: true
trading_pair_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Trading pair UUID
format: uuid
nullable: true
funding_rate:
example: '0.0015'
type: string
description: Funding rate applied for the epoch
nullable: true
position_size:
example: '2'
type: string
description: Absolute position size at settlement
nullable: true
payment_amount:
example: '150'
type: string
description: Signed funding payment amount; positive means paid, negative means received
nullable: true
direction:
example: PAID
type: string
description: Funding direction for the user
nullable: true
period_start:
example: 2026-04-07T10:00:00Z
type: string
description: Funding window start timestamp (ISO 8601)
nullable: true
period_end:
example: 2026-04-07T11:00:00Z
type: string
description: Funding window end timestamp (ISO 8601)
nullable: true
created_at:
example: 2026-04-07T11:00:00Z
type: string
description: Funding payment creation timestamp (ISO 8601)
nullable: true
FundingRecord:
type: object
properties:
trading_pair_id:
type: string
nullable: true
format: uuid
epoch:
type: string
nullable: true
funding_rate:
type: string
nullable: true
funding_delta_per_unit:
type: string
nullable: true
cumulative_funding_per_unit:
type: string
nullable: true
reference_price:
type: string
nullable: true
sample_count:
type: integer
format: uint32
nullable: true
window_started_at:
type: string
nullable: true
window_closed_at:
type: string
nullable: true
settled_at:
type: string
nullable: true
GetAppStatsResponse:
type: object
properties:
volume:
example: '12345.67'
type: string
description: Total quote volume (normalized, in human-readable quote token units) for trades where this application's users were the taker
nullable: true
maker_fee:
example: '12.34'
type: string
description: Total maker fees collected (normalized, in human-readable quote token units)
nullable: true
taker_fee:
example: '34.56'
type: string
description: Total taker fees collected (normalized, in human-readable quote token units)
nullable: true
application_taker_fee:
example: '5.67'
type: string
description: Application revenue share from taker fees (normalized, in human-readable quote token units)
nullable: true
trade_count:
nullable: true
type: string
description: Total number of trades
GetAvailableCollateralResponse:
type: object
properties:
asset:
type: string
nullable: true
wallet_available:
type: string
nullable: true
wallet_locked:
type: string
nullable: true
margin_transferable:
type: string
nullable: true
margin_available_collateral:
type: string
description: |-
Free collateral currently held in the user's parent margin account for this
asset (equity minus initial margin required), i.e. collateral already inside
margin and available to open new positions or transfer back out. Absent when
the user has no margin account yet.
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
total_balance_raw:
example: '1050750000'
type: string
description: Raw total balance (available + locked) in smallest token unit
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
GetFundingStateResponse:
type: object
properties:
trading_pair_id:
type: string
nullable: true
format: uuid
current_funding_rate:
type: string
nullable: true
estimated_next_funding_rate:
type: string
nullable: true
next_funding_time:
type: string
nullable: true
funding_interval_seconds:
type: integer
format: uint32
nullable: true
last_funding_time:
type: string
nullable: true
updated_at:
type: string
nullable: true
GetIndexPriceResponse:
type: object
properties:
trading_pair_id:
type: string
nullable: true
format: uuid
index_price:
type: string
nullable: true
components:
type: array
items:
$ref: '#/components/schemas/IndexComponent'
nullable: true
updated_at:
type: string
nullable: true
GetLimitsResponse:
type: object
properties:
limits:
type: array
items:
$ref: '#/components/schemas/SubAccountLimit'
nullable: true
GetMarginAccountMovementsResponse:
type: object
properties:
movements:
type: array
items:
$ref: '#/components/schemas/MarginAccountMovement'
nullable: true
total:
type: integer
format: uint32
nullable: true
page:
type: integer
format: uint32
nullable: true
page_size:
type: integer
format: uint32
nullable: true
GetMarginAccountSummaryResponse:
type: object
properties:
margin_account_id:
type: string
nullable: true
account_state:
type: string
nullable: true
equity:
type: string
nullable: true
initial_margin_required:
type: string
nullable: true
maintenance_margin_required:
type: string
nullable: true
free_collateral:
type: string
nullable: true
withdrawable_collateral:
type: string
nullable: true
total_position_notional:
type: string
nullable: true
unrealized_pnl:
type: string
nullable: true
realized_pnl:
type: string
nullable: true
updated_at:
type: string
nullable: true
label:
type: string
nullable: true
trading_pair_id:
type: string
nullable: true
format: uuid
strategy_key:
type: string
nullable: true
risk_bucket_id:
type: string
nullable: true
margin_mode:
type: string
nullable: true
GetMarkPriceResponse:
type: object
properties:
trading_pair_id:
type: string
nullable: true
format: uuid
mark_price:
type: string
nullable: true
oracle_provider:
type: string
nullable: true
oracle_epoch:
type: string
nullable: true
updated_at:
type: string
nullable: true
regime:
type: string
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
min_leverage:
example: '1'
type: string
description: Minimum supported leverage for margin markets
nullable: true
max_leverage:
example: '20'
type: string
description: Maximum supported leverage for margin markets
nullable: true
mark_price:
example: '95410.25'
type: string
description: Current manipulation-resistant mark price
nullable: true
index_price:
example: '95400.00'
type: string
description: Current index/oracle reference price
nullable: true
total_base_volume_ltd:
example: '123456.78900000'
type: string
description: Life-to-date cumulative base-token volume (since market inception); "0" for a pair with no trades yet
nullable: true
total_quote_volume_ltd:
example: '9123456789.50'
type: string
description: Life-to-date cumulative quote-token volume (since market inception); "0" for a pair with no trades yet
nullable: true
total_trade_count_ltd:
example: '482931'
type: string
description: Life-to-date cumulative number of trades (since market inception); 0 for a pair with no trades yet
nullable: true
description: Market metadata with current price and 24h statistics.
GetMarketStatsResponse:
type: object
properties:
total_quote_volume_ltd:
example: '48217365920.75'
type: string
description: Life-to-date cumulative quote-token (notional) volume summed across all trading pairs
nullable: true
total_trade_count_ltd:
example: '19284736'
type: string
description: Life-to-date cumulative number of trades summed across all trading pairs
nullable: true
description: Exchange-wide life-to-date cumulative market statistics across all trading pairs.
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
GetOpenInterestResponse:
type: object
properties:
trading_pair_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Trading pair UUID
format: uuid
nullable: true
open_interest:
example: '12345.67'
type: string
description: Current open interest in base-asset units
nullable: true
updated_at:
example: '1736742000000'
type: string
description: Timestamp of the latest open interest sample (ms since epoch)
nullable: true
open_interest_base:
example: '12345.67'
type: string
description: Current open interest in base-asset units
nullable: true
open_interest_notional:
example: '1172836500.00'
type: string
description: Current open interest notional in quote units
nullable: true
description: Latest public open interest for a trading pair.
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
margin_account_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Margin account UUID for margin orders
format: uuid
nullable: true
position_side:
example: LONG
type: string
description: Position side for margin orders
nullable: true
leverage:
example: '5'
type: string
description: Leverage for margin orders
nullable: true
reduce_only:
example: false
type: boolean
description: Whether the order is reduce-only
nullable: true
position_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Associated margin position UUID
format: uuid
nullable: true
quantity_raw:
example: '500000000'
type: string
description: Original order quantity in raw format (for precision)
nullable: true
filled_quantity_raw:
example: '200000000'
type: string
description: Filled quantity in raw format (for precision)
nullable: true
remaining_quantity:
example: '0.3'
type: string
description: Remaining unfilled quantity (normalized for display)
nullable: true
remaining_quantity_raw:
example: '300000000'
type: string
description: Remaining unfilled quantity in raw format (for precision)
nullable: true
client_order_id:
type: string
description: Client-assigned order identifier
nullable: true
cancelled_at:
example: 2023-11-13T10:35:00Z
type: string
description: Timestamp when the order was cancelled (ISO 8601)
nullable: true
filled_at:
example: 2023-11-13T10:35:00Z
type: string
description: Timestamp when the order was fully filled (ISO 8601)
nullable: true
expired_at:
example: 2023-11-13T10:35:00Z
type: string
description: Timestamp when the order expired (ISO 8601)
nullable: true
submitted_at:
example: 2023-11-13T10:35:00Z
type: string
description: Timestamp when the order was submitted (ISO 8601)
nullable: true
acknowledged_at:
example: 2023-11-13T10:35:00Z
type: string
description: Timestamp when the order was acknowledged (ISO 8601)
nullable: true
trigger_price:
example: '34000.00'
type: string
description: Trigger price for stop/conditional orders
nullable: true
quote_volume:
example: '17500.00'
type: string
description: Quote volume of the order
nullable: true
application_id:
type: string
description: Application UUID that created the order
format: uuid
nullable: true
parent_order_id:
type: string
description: Parent order UUID for linked orders
format: uuid
nullable: true
batch_id:
type: string
description: Batch UUID for batch orders
format: uuid
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.
GetPerpMarketConfigResponse:
type: object
properties:
trading_pair_id:
type: string
nullable: true
format: uuid
symbol:
type: string
nullable: true
min_leverage:
type: string
nullable: true
max_leverage:
type: string
nullable: true
initial_margin_ratio:
type: string
nullable: true
maintenance_margin_ratio:
type: string
nullable: true
funding_interval_seconds:
type: integer
format: uint32
nullable: true
liquidation_fee_bps:
type: string
nullable: true
risk_tiers:
type: array
items:
$ref: '#/components/schemas/RiskTier'
nullable: true
updated_at:
type: string
nullable: true
GetPerpMarketSummaryResponse:
type: object
properties:
trading_pair_id:
type: string
nullable: true
format: uuid
symbol:
type: string
nullable: true
last_price:
type: string
nullable: true
mark_price:
type: string
nullable: true
index_price:
type: string
nullable: true
high_24h:
type: string
nullable: true
low_24h:
type: string
nullable: true
volume_24h:
type: string
nullable: true
price_change_24h:
type: string
nullable: true
price_change_percent_24h:
type: string
nullable: true
open_interest:
type: string
nullable: true
current_funding_rate:
type: string
nullable: true
estimated_next_funding_rate:
type: string
nullable: true
next_funding_time:
type: string
nullable: true
market_status:
type: string
nullable: true
market_regime:
type: string
nullable: true
updated_at:
type: string
nullable: true
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
GetPositionResponse:
type: object
properties:
position_id:
type: string
nullable: true
margin_account_id:
type: string
description: Margin account UUID for the isolated bucket that owns this position.
nullable: true
trading_pair_id:
type: string
nullable: true
format: uuid
side:
type: string
nullable: true
size:
type: string
nullable: true
entry_price:
type: string
nullable: true
mark_price:
type: string
nullable: true
index_price:
type: string
nullable: true
unrealized_pnl:
type: string
nullable: true
realized_pnl:
type: string
nullable: true
isolated_margin:
type: string
description: Current isolated collateral for this position's margin-account bucket.
nullable: true
leverage:
type: string
nullable: true
maintenance_margin_required:
type: string
nullable: true
initial_margin_required:
type: string
nullable: true
liquidation_price:
type: string
nullable: true
status:
type: string
nullable: true
updated_at:
type: string
nullable: true
risk_bucket_id:
type: string
nullable: true
GetPositionRiskResponse:
type: object
properties:
position_id:
type: string
nullable: true
mark_price:
type: string
nullable: true
index_price:
type: string
nullable: true
unrealized_pnl:
type: string
nullable: true
liquidation_price:
type: string
nullable: true
margin_ratio:
type: string
nullable: true
maintenance_margin_required:
type: string
nullable: true
initial_margin_required:
type: string
nullable: true
updated_at:
type: string
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
GetScreenerResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/ScreenerItem'
nullable: true
page:
example: 1
type: integer
description: Current page number
format: uint32
nullable: true
page_size:
example: 50
type: integer
description: Items per page
format: uint32
nullable: true
total:
example: 37
type: integer
description: Total number of trading pairs after filtering
format: uint32
nullable: true
total_pages:
example: 1
type: integer
description: Total number of pages
format: uint32
nullable: true
description: Paginated screener response sorted by quote_volume_24h desc (nulls last).
GetTradeByIdResponse:
type: object
properties:
data:
$ref: '#/components/schemas/TradeData'
event_type:
example: trade
type: string
description: Event type identifier
nullable: true
trading_pair_id:
example: 456e7890-e12b-12d3-a456-426614174000
type: string
description: Trading pair UUID
format: uuid
nullable: true
trading_mode:
example: SPOT
type: string
description: 'Trading mode: SPOT or MARGIN'
nullable: true
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
IndexComponent:
type: object
properties:
provider:
type: string
nullable: true
price:
type: string
nullable: true
weight:
type: string
nullable: true
updated_at:
type: string
nullable: true
InitiateWithdrawalRequest:
type: object
properties:
asset_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: UUID of the asset to withdraw
format: uuid
nullable: true
amount:
example: '1000000000000000000'
type: string
description: Raw token amount in the smallest unit (e.g. wei) as a stringified positive integer
nullable: true
destination:
nullable: true
type: string
description: On-chain address that will receive the withdrawal (EVM, 42 chars including 0x)
source:
example: spot
type: string
description: 'Source ledger to withdraw from: "spot" (default) debits spot balance; "margin" directly debits withdrawable collateral from the parent margin account'
nullable: true
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
ListConditionalOrdersResponse:
type: object
properties:
orders:
type: array
items:
$ref: '#/components/schemas/ConditionalOrder'
nullable: true
total:
type: integer
format: uint32
nullable: true
page:
type: integer
format: uint32
nullable: true
page_size:
type: integer
format: uint32
nullable: true
ListDelegatedAgentOwnersResponse:
type: object
properties:
owners:
type: array
items:
$ref: '#/components/schemas/DelegatedAgentOwner'
description: Owners that have an active delegation to the calling agent
nullable: true
ListDelegatedAgentsResponse:
type: object
properties:
agents:
type: array
items:
$ref: '#/components/schemas/DelegatedAgent'
description: The calling owner's delegated agents
nullable: true
ListFundingHistoryResponse:
type: object
properties:
records:
type: array
items:
$ref: '#/components/schemas/FundingRecord'
nullable: true
total:
type: integer
format: uint32
nullable: true
page:
type: integer
format: uint32
nullable: true
page_size:
type: integer
format: uint32
nullable: true
ListFundingPaymentsResponse:
type: object
properties:
records:
type: array
items:
$ref: '#/components/schemas/FundingPaymentRecord'
nullable: true
total:
example: 2
type: integer
description: Total matching funding payment records
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
ListMarginAccountsResponse:
type: object
properties:
accounts:
type: array
items:
$ref: '#/components/schemas/MarginAccountSummary'
nullable: true
total:
type: integer
format: uint32
nullable: true
page:
type: integer
format: uint32
nullable: true
page_size:
type: integer
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
ListPositionHistoryResponse:
type: object
properties:
events:
type: array
items:
$ref: '#/components/schemas/PositionHistoryEvent'
nullable: true
total:
type: integer
format: uint32
nullable: true
page:
type: integer
format: uint32
nullable: true
page_size:
type: integer
format: uint32
nullable: true
ListPositionsResponse:
type: object
properties:
positions:
type: array
items:
$ref: '#/components/schemas/Position'
nullable: true
total:
type: integer
format: uint32
nullable: true
page:
type: integer
format: uint32
nullable: true
page_size:
type: integer
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.
MarginAccountMovement:
type: object
properties:
id:
type: string
nullable: true
movement_type:
type: string
nullable: true
asset:
type: string
nullable: true
amount:
type: string
nullable: true
status:
type: string
nullable: true
created_at:
type: string
nullable: true
MarginAccountSummary:
type: object
properties:
margin_account_id:
type: string
description: Parent margin account UUID.
nullable: true
account_state:
type: string
nullable: true
equity:
type: string
nullable: true
initial_margin_required:
type: string
nullable: true
maintenance_margin_required:
type: string
nullable: true
free_collateral:
type: string
nullable: true
withdrawable_collateral:
type: string
nullable: true
total_position_notional:
type: string
nullable: true
unrealized_pnl:
type: string
nullable: true
realized_pnl:
type: string
nullable: true
updated_at:
type: string
nullable: true
label:
type: string
nullable: true
trading_pair_id:
type: string
nullable: true
format: uuid
strategy_key:
type: string
nullable: true
risk_bucket_id:
type: string
description: Present only for risk-bucket summary rows.
nullable: true
margin_mode:
type: string
description: 'Present only for risk-bucket summary rows. Values: ISOLATED, CROSS.'
nullable: true
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
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'
ParentTpSlLeg:
type: object
properties:
trigger_price:
example: '65000'
type: string
description: Mark price that activates this TP/SL child
nullable: true
order_type:
enum:
- MARKET
- LIMIT
type: string
description: 'Triggered order type: MARKET or LIMIT'
nullable: true
limit_price:
example: '64950'
type: string
description: Limit price for LIMIT TP/SL children
nullable: true
time_in_force:
enum:
- GTC
- IOC
type: string
description: 'LIMIT only: GTC or IOC'
nullable: true
slippage_tolerance_bps:
example: 1000
maximum: 10000
type: integer
description: MARKET only slippage tolerance in basis points
format: int32
nullable: true
expires_at:
example: 2026-06-01T00:00:00Z
type: string
description: Optional conditional order expiry timestamp (ISO 8601)
nullable: true
Position:
type: object
properties:
position_id:
type: string
nullable: true
margin_account_id:
type: string
description: Margin account UUID for the isolated bucket that owns this position.
nullable: true
trading_pair_id:
type: string
nullable: true
format: uuid
side:
type: string
nullable: true
size:
type: string
nullable: true
entry_price:
type: string
nullable: true
mark_price:
type: string
nullable: true
index_price:
type: string
nullable: true
unrealized_pnl:
type: string
nullable: true
realized_pnl:
type: string
nullable: true
isolated_margin:
type: string
description: Current isolated collateral for this position's margin-account bucket.
nullable: true
leverage:
type: string
nullable: true
maintenance_margin_required:
type: string
nullable: true
initial_margin_required:
type: string
nullable: true
liquidation_price:
type: string
nullable: true
status:
type: string
nullable: true
updated_at:
type: string
nullable: true
risk_bucket_id:
type: string
nullable: true
PositionHistoryEvent:
type: object
properties:
id:
type: string
nullable: true
position_id:
type: string
nullable: true
margin_account_id:
type: string
nullable: true
trading_pair_id:
type: string
nullable: true
format: uuid
action:
type: string
nullable: true
size_change:
type: string
nullable: true
price:
type: string
nullable: true
realized_pnl:
type: string
nullable: true
fees_paid:
type: string
nullable: true
collateral_change:
type: string
nullable: true
order_id:
type: string
nullable: true
format: uuid
created_at:
type: string
nullable: true
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:
data:
$ref: '#/components/schemas/TradeData'
event_type:
example: trade
type: string
description: Event type identifier
nullable: true
trading_pair_id:
example: 456e7890-e12b-12d3-a456-426614174000
type: string
description: Trading pair UUID
format: uuid
nullable: true
trading_mode:
example: SPOT
type: string
description: 'Trading mode: SPOT or MARGIN'
nullable: true
description: 'A public trade event. Serializes to the historical REST/WebSocket envelope: { data: { ... }, event_type, trading_pair_id, trading_mode }.'
ReducePositionMarginRequest:
type: object
properties:
amount:
type: string
nullable: true
ReducePositionMarginResponse:
type: object
properties:
position_id:
type: string
nullable: true
margin_account_id:
type: string
description: Margin account UUID for the isolated bucket that was adjusted.
nullable: true
new_isolated_margin:
type: string
nullable: true
status:
type: string
nullable: true
message:
type: string
nullable: true
RefreshRequest:
type: object
properties: {}
additionalProperties: false
RefreshResponse:
type: object
properties:
expires_at:
example: 1699876543
type: integer
description: Unix timestamp when the session expires after refresh
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'
RevokeDelegatedAgentResponse:
type: object
properties:
status:
example: REVOKED
type: string
description: Revocation status
nullable: true
RevokeRequest:
type: object
properties: {}
additionalProperties: false
RevokeResponse:
type: object
properties:
message:
example: Session revoked successfully
type: string
description: Human-readable status message
nullable: true
RiskTier:
type: object
properties:
initial_margin_ratio:
type: string
nullable: true
maintenance_margin_ratio:
type: string
nullable: true
max_position_notional:
type: string
nullable: true
ScreenerItem:
type: object
properties:
trading_pair_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Trading pair UUID
format: uuid
nullable: true
symbol:
example: BTC/USDC
type: string
description: Trading pair symbol
nullable: true
base_icon_url:
example: https://assets.0xmonaco.com/icons/btc.svg
type: string
description: URL for the base token icon
nullable: true
quote_icon_url:
example: https://assets.0xmonaco.com/icons/usdc.svg
type: string
description: URL for the quote token icon
nullable: true
last_price:
example: '95432.50'
type: string
description: Most recent close price
nullable: true
last_price_timestamp:
example: '1745308800000'
type: string
description: Timestamp of the last candle (ms since epoch)
nullable: true
quote_volume_1h:
example: '1178245.32'
type: string
description: Quote-token volume in the last 1 hour
nullable: true
quote_volume_24h:
example: '117845632.18'
type: string
description: Quote-token volume in the last 24 hours
nullable: true
quote_volume_7d:
example: '851234109.44'
type: string
description: Quote-token volume in the last 7 days
nullable: true
price_change_percent_1h:
example: '0.42'
type: string
description: Percent price change over the last 1 hour
nullable: true
price_change_percent_24h:
example: '1.31'
type: string
description: Percent price change over the last 24 hours
nullable: true
price_change_percent_7d:
example: '-3.87'
type: string
description: Percent price change over the last 7 days
nullable: true
snapshot_7d:
type: array
items:
$ref: '#/components/schemas/ScreenerSnapshotPoint'
description: Up to 7 UTC-day buckets (oldest first); empty when <1 day of history
nullable: true
category:
example: crypto
type: string
description: 'Asset-class category: crypto, equities, commodities, or fx'
nullable: true
total_quote_volume_ltd:
example: '9123456789.50'
type: string
description: Life-to-date cumulative quote-token volume (since market inception); "0" for a pair with no trades yet
nullable: true
total_trade_count_ltd:
example: '482931'
type: string
description: Life-to-date cumulative number of trades (since market inception); 0 for a pair with no trades yet
nullable: true
description: Per-pair screener row. Window fields null when insufficient history.
ScreenerSnapshotPoint:
type: object
properties:
bucket_start:
example: '1744704000000'
type: string
description: UTC day boundary (ms since epoch)
nullable: true
quote_volume:
example: '105204321.11'
type: string
description: Quote-token volume for the day
nullable: true
price_change_percent:
example: '0.85'
type: string
description: Percent price change (close - open) / open * 100 for the day
nullable: true
description: One UTC-day bucket in a pair's 7-day snapshot.
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
SimulateOrderRiskRequest:
type: object
properties:
margin_account_id:
type: string
description: Margin account UUID for the isolated bucket being simulated.
nullable: true
trading_pair_id:
type: string
nullable: true
format: uuid
side:
type: string
nullable: true
position_side:
type: string
nullable: true
order_type:
type: string
nullable: true
price:
type: string
nullable: true
quantity:
type: string
nullable: true
leverage:
type: string
nullable: true
reduce_only:
type: boolean
nullable: true
SimulateOrderRiskResponse:
type: object
properties:
accepted:
type: boolean
nullable: true
reject_reason:
type: string
nullable: true
equity_after:
type: string
nullable: true
initial_margin_required_after:
type: string
nullable: true
maintenance_margin_required_after:
type: string
nullable: true
free_collateral_after:
type: string
nullable: true
estimated_fee:
type: string
nullable: true
estimated_liquidation_price:
type: string
nullable: true
margin_account_id:
type: string
description: |-
The margin account the simulation was resolved against. Always populated;
useful for auto-resolved buckets where the caller didn't supply the id.
nullable: true
strategy_key:
type: string
description: Populated when the simulated account is an auto-resolved bucket.
nullable: true
SimulateParentMarginOrderRiskRequest:
type: object
properties:
trading_pair_id:
type: string
nullable: true
format: uuid
side:
type: string
nullable: true
position_side:
type: string
nullable: true
order_type:
type: string
nullable: true
price:
type: string
nullable: true
quantity:
type: string
nullable: true
leverage:
type: string
nullable: true
reduce_only:
type: boolean
nullable: true
SimulateRiskBucketOrderRiskRequest:
type: object
properties:
trading_pair_id:
type: string
nullable: true
format: uuid
strategy_key:
type: string
nullable: true
side:
type: string
nullable: true
position_side:
type: string
nullable: true
order_type:
type: string
nullable: true
price:
type: string
nullable: true
quantity:
type: string
nullable: true
leverage:
type: string
nullable: true
reduce_only:
type: boolean
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
TpSlLeg:
type: object
properties:
trigger_price:
type: string
nullable: true
order_type:
type: string
nullable: true
limit_price:
type: string
nullable: true
quantity:
type: string
nullable: true
time_in_force:
type: string
nullable: true
slippage_tolerance_bps:
type: integer
format: int32
nullable: true
expires_at:
type: string
nullable: true
TradeData:
type: object
properties:
executed_at:
example: 2023-11-13T10:30:00Z
type: string
description: Trade execution timestamp (ISO 8601). Omitted when the trade has no execution time.
nullable: true
maker_side:
example: BUY
type: string
description: 'Maker order side: BUY or SELL'
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 (normalized)
nullable: true
quantity_raw:
example: '50000000'
type: string
description: Traded quantity in raw base-token units
nullable: true
trade_id:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
description: Trade UUID
format: uuid
nullable: true
description: Core fields of a single executed trade, nested under `data` in the public trade event envelope.
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
min_leverage:
example: '1'
type: string
description: Minimum supported leverage for margin markets
nullable: true
max_leverage:
example: '20'
type: string
description: Maximum supported leverage for margin markets
nullable: true
category:
example: crypto
type: string
description: 'Asset-class category: crypto, equities, commodities, or fx'
nullable: true
description: Trading pair configuration including tokens, fees, and order limits.
TransferCollateralFromMarginAccountRequest:
type: object
properties:
margin_account_id:
type: string
description: Parent margin account UUID that releases collateral.
nullable: true
asset:
type: string
nullable: true
amount:
type: string
nullable: true
trading_pair_id:
type: string
description: |-
Optional trading pair UUID used to release collateral from an isolated risk
bucket under the parent margin account. If omitted, the transfer applies to
the parent margin account only.
nullable: true
format: uuid
strategy_key:
type: string
description: Optional strategy key echoed in responses when callers scope a risk bucket.
nullable: true
TransferCollateralFromMarginAccountResponse:
type: object
properties:
movement_id:
type: string
nullable: true
margin_account_id:
type: string
nullable: true
asset:
type: string
nullable: true
amount:
type: string
nullable: true
status:
type: string
nullable: true
new_equity:
type: string
nullable: true
new_total_collateral_value:
type: string
nullable: true
new_withdrawable_collateral:
type: string
nullable: true
strategy_key:
type: string
nullable: true
TransferCollateralFromParentMarginAccountRequest:
type: object
properties:
asset:
type: string
nullable: true
amount:
type: string
nullable: true
TransferCollateralToMarginAccountRequest:
type: object
properties:
margin_account_id:
type: string
description: Parent margin account UUID that receives collateral.
nullable: true
asset:
type: string
nullable: true
amount:
type: string
nullable: true
trading_pair_id:
type: string
description: |-
Optional trading pair UUID used to allocate collateral to an isolated risk
bucket under the parent margin account. If omitted, the transfer applies to
the parent margin account only.
nullable: true
format: uuid
strategy_key:
type: string
description: Optional strategy key echoed in responses when callers scope a risk bucket.
nullable: true
TransferCollateralToMarginAccountResponse:
type: object
properties:
movement_id:
type: string
nullable: true
margin_account_id:
type: string
nullable: true
asset:
type: string
nullable: true
amount:
type: string
nullable: true
status:
type: string
nullable: true
new_equity:
type: string
nullable: true
new_total_collateral_value:
type: string
nullable: true
new_withdrawable_collateral:
type: string
nullable: true
strategy_key:
type: string
nullable: true
TransferCollateralToParentMarginAccountRequest:
type: object
properties:
asset:
type: string
nullable: true
amount:
type: string
nullable: true
TransferCollateralToRiskBucketRequest:
type: object
properties:
asset:
type: string
nullable: true
amount:
type: string
nullable: true
trading_pair_id:
type: string
description: Trading pair UUID whose risk bucket receives collateral.
nullable: true
format: uuid
strategy_key:
type: string
nullable: true
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
UpsertDelegatedAgentRequest:
type: object
properties:
agent_address:
nullable: true
type: string
description: Agent wallet address (EVM, 42 chars including 0x)
name:
example: market-maker-bot
type: string
description: Optional human-friendly label for the agent
nullable: true
expires_at:
example: 2026-12-31T23:59:59Z
type: string
description: Optional delegation expiry timestamp (ISO 8601). Omit for no expiry.
nullable: true
allowed_actions:
example:
- CREATE_ORDER
- CANCEL_ORDER
type: array
items:
type: string
minLength: 1
description: 'Actions the agent may perform: CREATE_ORDER, CANCEL_ORDER, REPLACE_ORDER'
nullable: true
allowed_trading_pair_ids:
type: array
items:
type: string
minLength: 1
format: uuid
description: Trading pair UUIDs the agent may trade. An order is allowed if its market or its margin account is permitted.
nullable: true
allowed_margin_account_ids:
type: array
items:
type: string
minLength: 1
format: uuid
description: Margin account UUIDs the agent may trade against. An order is allowed if its market or its margin account is permitted.
nullable: true
allowed_order_types:
example:
- LIMIT
type: array
items:
type: string
minLength: 1
description: Permitted order types (LIMIT, MARKET). Empty means unrestricted.
nullable: true
allowed_time_in_force:
example:
- GTC
type: array
items:
type: string
minLength: 1
description: Permitted time-in-force values (GTC, IOC, FOK). Empty means unrestricted.
nullable: true
max_leverage:
example: '10'
type: string
description: Maximum leverage the agent may use (decimal string). Omit for no limit.
nullable: true
max_order_notional:
example: '50000'
type: string
description: Maximum order notional (price * quantity, decimal string). Omit for no limit.
nullable: true
max_open_orders:
example: 100
type: integer
description: Maximum concurrent open orders. Omit for no limit.
format: int32
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:
type: string
nullable: true
order_id:
type: string
nullable: true
format: uuid
position_id:
type: string
nullable: true
trading_pair_id:
type: string
nullable: true
format: uuid
side:
type: string
nullable: true
price:
type: string
nullable: true
quantity:
type: string
nullable: true
liquidity_role:
type: string
nullable: true
fee:
type: string
nullable: true
realized_pnl:
type: string
nullable: true
timestamp:
type: string
nullable: true
VerifyRequest:
required:
- address
- signature
- nonce
- session_public_key
type: object
properties:
address:
description: Ethereum wallet address
maxLength: 42
minLength: 42
pattern: ^0x[0-9a-fA-F]{40}$
type: string
signature:
description: Wallet signature over the challenge 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
session_public_key:
example: 3b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29
maxLength: 64
minLength: 64
pattern: ^[0-9a-f]{64}$
type: string
description: Lowercase hex (64 chars) ed25519 public key generated locally by the SDK. Subsequent authenticated requests are signed with the matching private key. The wallet's signature on the challenge message proves the user authorized this specific public key.
additionalProperties: false
VerifyResponse:
type: object
properties:
expires_at:
example: 1699876543
type: integer
description: Unix timestamp when the session expires
format: int32
nullable: true
user:
$ref: '#/components/schemas/UserInfo'
Withdrawal:
type: object
properties:
withdrawal_index:
nullable: true
type: string
description: Allocated withdrawal index — matches executeWithdrawal.index on-chain
vault_address:
nullable: true
type: string
description: 0x-prefixed lowercase address of the vault contract the calldata is submitted to
calldata:
type: string
description: 0x-prefixed ABI-encoded executeWithdrawal(...) calldata; submit as tx.data to the vault. Empty on InitiateWithdrawal (the merkle proof is not available until the withdrawal root is confirmed on-chain) — fetch it from GetWithdrawal once ready
nullable: true
securitySchemes:
monacoSignature:
type: apiKey
description: 'Ed25519 session-key request signing. Every authenticated request carries three headers: `X-Monaco-PublicKey` (64-char lowercase-hex session public key), `X-Monaco-Timestamp` (Unix milliseconds, within 30s of server time), and `X-Monaco-Signature` (hex ed25519 signature). The signature is over `METHOD\npath?query\ntimestamp_ms\nSHA256_hex(body)`, where the body hash is the SHA-256 of the empty byte string when there is no body. Obtain the session keypair from `POST /api/v1/auth/challenge` followed by `POST /api/v1/auth/verify`.'
name: X-Monaco-Signature
in: header
apiKey:
type: apiKey
name: x-server-key
in: header
tags:
- name: AccountsService
- name: ApplicationsService
- name: AuthService
- name: DelegatedAgentsService
- name: FaucetService
- name: FeesService
- name: HealthService
- name: MarginAccountsService
description: |-
Current public isolated-margin semantics:
- a user has one parent margin account per application scope
- opening orders create or reuse isolated position buckets under that parent
- parent account creation is handled internally by margin workflows
- name: MarketService
- name: OrderbookService
- name: OrdersService
- name: PositionsService
description: |-
Current public isolated-margin semantics:
- positions link to a parent margin account and, when applicable, a bucket id
- opening orders create or reuse isolated position buckets under the parent
- users can open another isolated position by reusing the parent account with a different market bucket
- name: TradesService
- name: WhitelistService
- name: WithdrawalsService