Profile

import { MonacoSDK } from "@0xmonaco/core";

// Initialize SDK with wallet client (see Initialization guide)

// Profile data
await sdk.profile.getProfile();

// Get all user balances with pagination
await sdk.profile.getUserBalances({ page: 1, pageSize: 20 });

// Get balance for a specific asset (by UUID)
await sdk.profile.getUserBalanceByAssetId('123e4567-e89b-12d3-a456-426614174000');

// Transaction history with optional filters
await sdk.profile.getPaginatedUserMovements({ page: 1, pageSize: 20 });
await sdk.profile.getPaginatedUserMovements({ entryType: "CREDIT", transactionType: "DEPOSIT" });
await sdk.profile.getPaginatedUserMovements({ assetId: "123e4567-e89b-12d3-a456-426614174000" });

// Trade history (cursor-paginated by default; follow nextPageToken)
await sdk.profile.getUserTrades({ pageSize: 20 });
await sdk.profile.getUserTrades({ tradingPairId: '123e4567-e89b-12d3-a456-426614174000' });

// Funding payment history (margin positions)
await sdk.profile.listFundingPayments({ page: 1, pageSize: 20 });
await sdk.profile.listFundingPayments({ tradingPairId: '123e4567-e89b-12d3-a456-426614174000' });

// Sub-accounts (master account)
await sdk.subAccounts.list();

// Testnet faucet (a valid Cloudflare Turnstile token is required on every mint)
await sdk.faucet.mint({ turnstileToken: "<turnstile-token>" });

Profile Data

() => Promise<UserProfile>

Retrieve the authenticated user’s core profile metadata.Returns:

id: Unique user identifier
address: Wallet address
username: Display name (nullable)
accountType: Account type (e.g. "master")
canWithdraw: Whether the account can withdraw funds
takerFeeBps: Deprecated. Flat taker fee rate in basis points; echoes the pre-tiered pair-level rate, not the per-user tiered fee. Use fees.getMyFeeTier for the caller’s real rate
makerFeeBps: Deprecated. Flat maker fee rate in basis points; echoes the pre-tiered pair-level rate, not the per-user tiered fee. Use fees.getMyFeeTier for the caller’s real rate
applicationTakerFeeBps: Additional taker fee in basis points contributed by the application, if any (optional)
applicationMakerFeeBps: Additional maker fee in basis points contributed by the application, if any (optional)
createdAt: Account creation timestamp (ISO 8601)

Token Balances

(params?) => Promise<GetUserBalancesResponse>

Fetch paginated token balances for the authenticated userParameters:

page (optional): Page number, starts from 1 (default: 1)
pageSize (optional): Number of items per page, max 100 (default: 20)

Returns:

balances: Array of AccountBalance objects
page: Current page number
pageSize: Items per page
total: Total number of balances
totalPages: Total number of pages

(assetId: string) => Promise<AccountBalance>

Get the user’s balance for a specific asset by its UUIDParameters:

assetId: Asset UUID (e.g., ‘123e4567-e89b-12d3-a456-426614174000’)

Returns:

token: Token contract address
symbol: Token symbol
decimals: Token decimal places
availableBalance: Available balance for trading
lockedBalance: Balance locked in orders
totalBalance: Total balance (available + locked)
version (optional): Opaque, non-negative spot-row revision. Compare only for the same authenticated user, application, and token; higher is newer. Absent and 0 both mean unranked and never participate in ordering: the row predates this field or came from a producer that does not stamp it, so normalize both to the same thing and fall back to a full field comparison rather than ranking an unranked row as oldest. A server mid-rolling-deploy sends no key at all, and undefined <= n is false, so an un-normalized guard silently passes.

Transaction History

(params?) => Promise<GetPaginatedUserMovementsResponse>

Fetch paginated ledger history — deposits, withdrawals, trades, fees, funding payments, liquidations, interest, rewards, and collateral transfers — with optional server-side filteringParameters:

page (optional): Page number, starts from 1 (default: 1)
pageSize (optional): Number of items per page, max 100 (default: 20)
entryType (optional): Filter by entry type — LedgerEntryType: "CREDIT", "DEBIT", "LOCK", "UNLOCK", "FEE"
transactionType (optional): Filter by transaction type — TransactionType: "DEPOSIT", "WITHDRAWAL", "TRADE", "FEE", "FUNDING", "LIQUIDATION", "INTEREST", "REWARD". Filter values and returned values are both upper-case (a funding row reports transactionType: "FUNDING", entryType: "DEBIT" | "CREDIT"), and the server matches the filter case-insensitively. The lower-case forms are the live movements WebSocket shape, not this one
assetId (optional): Filter by asset UUID

Returns:

movements: Array of LedgerMovement objects. A funding row is a collateral USD delta rather than a token transfer: amount is a magnitude with the direction in entryType, decimals is 0, and amountRaw equals amount. It shares its id with the live movements WebSocket frame, so dedupe by id across the two feeds — but the two payloads are not identical: the REST row is upper-case and resolves assetId, symbol and decimals — falling back to the pair’s quote asset when the margin account’s collateral binding is unset, so these carry a real asset rather than a placeholder, while the WebSocket frame is lower-case and carries no resolved asset id. See Account Balances
page: Current page number
pageSize: Items per page
total: Total number of movements
totalPages: Total number of pages

Portfolio Analytics

Portfolio analytics are documented on the Portfolio Analytics page. That page covers the authoritative sdk.portfolio methods as well as the older sdk.profile.getPortfolioStats and sdk.profile.getPortfolioChart.

Trade History

(params?) => Promise<GetUserTradesResponse>

Fetch trade history for the authenticated user, cursor-paginated by default. Legacy page-number (offset) pagination is deprecated but still available by passing page.Parameters: all optional

pageSize: Number of items per page (default: 20); max 1000 in cursor mode (the default), max 100 in legacy page-number mode
tradingPairId: Filter by trading pair UUID
pageToken: Pagination cursor:
- omitted — the SDK starts a cursor walk (pageToken=""), unless the deprecated page was passed
- "" (empty string) — start a cursor walk over full trade history (hot and archived rows merged), newest first
- a previous nextPageToken — resume the walk from that cursor
page: deprecated — legacy page-number pagination over the recent hot window only; ignored whenever pageToken is present

Returns:

trades: Array of UserTrade objects
pageSize: Items per page
nextPageToken: Cursor for the next page — non-empty whenever a page returns rows, empty when the walk is exhausted or in legacy page-number mode
page, total, totalPages: deprecated — legacy page-number mode only; 0 in cursor mode. In page-number mode the counts are exact up to the pagination reach and saturate there (total at pageSize × 10,000 rows, totalPages at 10,000 pages), and page itself is capped at 10,000. Cursor mode has no total — build “load more” UIs on nextPageToken instead of “page N of M”.

UserTrade fields:

tradeId: Trade unique identifier
tradingPairId: Trading pair UUID
price: Execution price (normalized string)
quantity: Executed quantity (normalized string)
quoteVolume: Price × quantity (normalized string)
side: "BUY" or "SELL" from the user’s perspective
fee: Fee paid for this trade (normalized string)
executedAt: Trade execution timestamp (ISO 8601)

(params?) => AsyncGenerator<UserTrade>

Walk full trade history with cursor pagination, yielding one trade at a time. Accepts tradingPairId and pageSize; the cursor is managed internally.

for await (const trade of sdk.profile.iterateUserTrades()) {
  // process trade
}

Funding Payments

(params?) => Promise<ListFundingPaymentsResponse>

Fetch the authenticated user’s funding payment history for margin positions, with pagination and optional filters.Parameters:

page (optional): Page number, starts from 1 (default: 1)
pageSize (optional): Number of items per page, max 100 (default: 20)
tradingPairId (optional): Filter by trading pair UUID
positionId (optional): Filter by margin position UUID
marginAccountId (optional): Filter by margin account UUID

Returns:

records: Array of FundingPayment objects
total: Total number of matching records
page: Current page number
pageSize: Items per page
totalPages: Total number of pages

FundingPayment fields:

id: Funding payment UUID
positionId: Margin position UUID
marginAccountId: Margin account UUID
tradingPairId: Trading pair UUID
fundingRate: Funding rate applied for the epoch (normalized string)
positionSize: Absolute position size at settlement (normalized string)
paymentAmount: Signed funding amount; positive means paid, negative means received (normalized string)
direction: "PAID" or "RECEIVED"
periodStart: Funding window start timestamp (ISO 8601, optional)
periodEnd: Funding window end timestamp (ISO 8601, optional)
createdAt: Funding payment creation timestamp (ISO 8601, optional)

Self-Trade Prevention Default

() => Promise<SelfTradePreventionDefault>

Read the wallet’s self-trade-prevention default — the mode the matching engine applies to an order that does not carry its own selfTradePreventionMode.Returns:

mode: "CANCEL_MAKER" | "CANCEL_TAKER" | "CANCEL_BOTH" | "SKIP" — the effective mode
isCustom: boolean — true when this wallet explicitly set a default, false when the platform default CANCEL_MAKER is being inherited

The setting is wallet-scoped: one default per wallet address, shared by every application and account using it. The read serves an asynchronous projection, so a read issued immediately after setSelfTradePreventionDefault can briefly lag that call’s own response.Throws:

REST 400 / gRPC InvalidArgument when the authenticated session’s wallet is not a canonical EVM address (0x + 40 hex) — the setting is keyed by wallet, so a legacy non-EVM session has none to read
REST 401 / gRPC Unauthenticated when authentication is missing or invalid
REST 403 / gRPC PermissionDenied when a delegated-agent session calls it — an agent can neither read nor set this default
REST 429 / gRPC ResourceExhausted once read-budget enforcement is enabled: this is an authenticated read and draws your account’s shared read budget, with the retry interval on the body’s details.retryAfter or a gRPC RetryInfo detail. See Rate limits
REST 500 / gRPC Internal for an internal failure

const stp = await sdk.profile.getSelfTradePreventionDefault();
console.log(`Mode: ${stp.mode} (explicitly set: ${stp.isCustom})`);

(mode: SelfTradePreventionMode) => Promise<SelfTradePreventionDefault>

Set the wallet’s self-trade-prevention default. See Self-Trade Prevention for what each mode does.Parameters:

mode: "CANCEL_MAKER" | "CANCEL_TAKER" | "CANCEL_BOTH" | "SKIP" — the SDK validates against these exact uppercase tokens and throws before sending, so pass them verbatim. The lowercase forms the server would accept never reach it

Returns: the setting now in force, same shape as getSelfTradePreventionDefault.The write is sequenced through the matching engine and returns only after the durable append, so the wallet’s next order already resolves the new mode. A per-order selfTradePreventionMode always overrides this default.The call sets the mode outright rather than applying a delta, so sending the same mode again is safe and a retry after a lost response cannot land a different value than the one you asked for. Concurrent sets for one wallet are last-write-wins in sequencer order, so serialize them per wallet if the final mode matters, and re-read with getSelfTradePreventionDefault after a transient failure rather than assuming the write was lost.Throws:

ValidationError (exported by @0xmonaco/types) when mode is not one of the four tokens — thrown before any network request
REST 400 / gRPC InvalidArgument when a raw caller sends an unknown mode, or when the authenticated session’s wallet is not a canonical EVM address (0x + 40 hex)
REST 401 / gRPC Unauthenticated when authentication is missing or invalid
REST 403 / gRPC PermissionDenied when a delegated-agent session attempts the change
REST 500 / gRPC Internal for an internal failure
REST 503 / gRPC Unavailable when the matching engine is unreachable or the sequenced write fails transiently. Do not read it as proof the setting is unchanged — the outcome is unknown: is_transient_me_failure also classifies DeadlineExceeded and Cancelled as transient, so the sequenced write may have committed before the response was lost. Re-read with the getter, or simply retry the same mode — the call sets an absolute value, so a replay cannot land anything other than what you asked for

const stp = await sdk.profile.setSelfTradePreventionDefault("SKIP");
console.log(`Mode is now ${stp.mode}`);

Sub-Accounts

Manage a master account’s sub-accounts and their per-asset spending limits. All methods are session-authenticated. The limit mutations (createLimit, updateLimit, deleteLimit) additionally require the master account to hold the ManageSubAccounts permission — enforced server-side, so a non-master or unpermissioned caller receives a 403.

() => Promise<ListSubAccountsResponse>

List the authenticated master account’s sub-accounts with their balances.Returns:

subAccounts: Array of SubAccount objects, each with id, address, username (nullable), canWithdraw, createdAt, and balances (array of AccountBalance)
total: Total number of sub-accounts

(body: CreateSubAccountLimitRequest) => Promise<CreateSubAccountLimitResponse>

Create a per-asset spending limit on a sub-account. Requires the ManageSubAccounts permission.Body:

subAccountId: Sub-account UUID to create the limit for
assetId: Asset UUID to limit
maxAmount: Maximum amount allowed, in token units (string)
dailyLimit (optional): Maximum daily spending limit, in token units (string)

Returns: { limit } — the created SubAccountLimit.

(subAccountId: string) => Promise<GetSubAccountLimitsResponse>

Get the limits configured for a sub-account.Parameters:

subAccountId: Sub-account UUID

Returns: { limits } — array of SubAccountLimit objects.

(subAccountId: string, assetId: string, body: UpdateSubAccountLimitBody) => Promise<UpdateSubAccountLimitResponse>

Partially update a sub-account’s per-asset limit. Requires the ManageSubAccounts permission. The sub-account and asset are taken from the path; all body fields are optional.Parameters:

subAccountId: Sub-account UUID
assetId: Asset UUID

Body (all optional):

maxAmount: New maximum amount, in token units (string)
dailyLimit: New maximum daily spending limit, in token units (string)
isActive: Whether the limit is active

Returns: { limit } — the updated SubAccountLimit.

(subAccountId: string, assetId: string) => Promise<void>

Delete a sub-account’s per-asset limit. Requires the ManageSubAccounts permission. Resolves with no value.Parameters:

subAccountId: Sub-account UUID
assetId: Asset UUID

Faucet

(params: MintTokensParams) => Promise<MintTokensResponse>

Mint the full set of testnet tokens to the authenticated user. Testnet-only, session-authenticated, and rate-limited per user (default 1 request / 24h). Performs real on-chain mints and resolves only when every token confirms on-chain; it throws on 429 (quota exhausted), 502 (mints failed or only partially confirmed — the error carries the minted/failed breakdown), or 503 (faucet unavailable, safe to retry). Wrap the call in a try/catch.Parameters:

turnstileToken: string (required) - Cloudflare Turnstile captcha token. Requests without a valid token are rejected with 400.

Returns (on resolve):

minted: Array of confirmed minted tokens, each with assetId, symbol, amount, txHash. A mint credits spot and margin separately, so a token can appear twice — once as USDC and once as USDC (margin)
failed: Array of tokens that failed to mint (assetId, symbol, error); empty on a successful resolve — populated on the thrown 502 error instead
remainingRequests24h: Remaining faucet requests in the next 24h

Learn

Build

Libraries

APIs

Resources

Profile Data

Token Balances

Transaction History

Portfolio Analytics

Trade History

Funding Payments

Self-Trade Prevention Default

Sub-Accounts

Faucet

​Profile Data

​Token Balances

​Transaction History

​Portfolio Analytics

​Trade History

​Funding Payments

​Self-Trade Prevention Default

​Sub-Accounts

​Faucet

Profile Data

Token Balances

Transaction History

Portfolio Analytics

Trade History

Funding Payments

Self-Trade Prevention Default

Sub-Accounts

Faucet