Concepts

Core concepts for Alpha Ladder AgentX — account model, currency typing, fees, minor units, verification codes, module permissions, and error shapes.

This page defines the data model and conventions shared across all AgentX MCP tools. Read this before working with any AgentX tool.

Account model

A Alpha Ladder account is partitioned into named sub-accounts called product accounts, each identified by a productCode enum value:

`productCode`	Description
`fiat`	Fiat currency account (USD, HKD, EUR, etc.)
`investment_fiat`	Fiat funds currently locked in an investment product
`quarantine_portfolio`	Assets frozen under compliance review
`investment_product`	Balance held in investment products such as FIP
`named_account`	Same-name account balance — funds held in accounts registered under the holder's own name

Use get_account_summary to see USD-equivalent totals across all categories. Use get_account_detail with a specific productCode to drill into individual currency balances.

The investment_product account returns an empty instrumentInfoMap ({}); it has no per-currency breakdown.

First-party vs third-party (COBO)

Many deposit and withdrawal tools accept a withdrawalParty parameter that distinguishes between two counterparty modes:

Value	Meaning
`1` (integer) or `'first_party'` (string enum)	The account owner is the counterparty — own bank account
`2` (integer) or `'third_party'` (string enum)	A COBO third-party counterparty — someone else's bank account

The exact type (integer 1/2 vs string 'first_party'/'third_party') varies per tool — see the individual tool parameter tables in MCP Tools.

Third-party requirements:

purposeOfTransaction (free text) is always required when withdrawalParty = 2 on execute calls.

Fees and charge types

chargeType (integer, used in execute_fiat_withdrawal) specifies who bears the bank transfer charge:

`chargeType`	Meaning
`1`	Fee borne by beneficiary
`2`	Fee borne by sender
`3`	Shared between both parties

feePayer (string enum, used in deposit estimate tools) controls service fee allocation:

`feePayer`	Meaning
`'paid_by_me'`	Fee deducted from the deposit amount — the user's net received amount is shown
`'paid_by_third_party'`	Fee added on top — the payor's gross send amount is shown

Use get_withdrawal_quote before executing a withdrawal to retrieve both the service fee (fee.serviceFee) and the minimum allowed amount (minimumAmount.minimumAmount) in a single call.

Minor units

The history list endpoints — get_deposit_list and get_withdrawal_list — return monetary amounts as integers in minor units (e.g. cents for USD):

totalAmount, receiveAmount, chargeAmount — all minor units.
Divide by 10^decimals before displaying. The decimal precision per currency is determined by the product base list.

Example: a USD amount of 150025 represents $1,500.25 (USD has 2 decimal places). The execute tool (execute_fiat_withdrawal) and account tools use decimal strings ("1500.25") — no conversion needed.

Verification codes

The execute-level withdrawal tool (execute_fiat_withdrawal) requires a verificationCode parameter. This is a time-limited one-time code issued by Alpha Ladder's security verification flow. MCP does not generate this code for you.

Before calling the execute-level withdrawal tool:

Ensure the user has already obtained a currently valid verification code from Alpha Ladder.
Treat the code as user-held input, not as a value that can be derived from another MCP tool call.
Do not cache or reuse an old code across sessions or after a failed attempt.
If the code is missing, invalid, or expired, stop the flow and ask the user to obtain a new one before retrying.

Passing an invalid or expired code results in a server-side validation error.

Module permissions

Before attempting any operation, call get_module_permissions to verify the current user has access to the relevant module:

Module	Controls
`deposit`	`get_fiat_deposit_*`, `get_deposit_bank_account`, deposit estimate/submit tools
`otc`	`get_available_currency_pairs`, `get_exchange_quote`, `get_otc_quote`, `confirm_otc_trade`, `get_otc_trade_detail`
`withdrawal`	`get_withdrawal_*`, `get_fiat_withdrawal_bank_accounts`, `execute_fiat_withdrawal`
`wealth`	`get_fip_products`, `get_fip_agreement`, `investor_precheck`, `fip_subscribe`

The tool returns an array of { module, hasPermission } objects. Attempting a module operation without the corresponding permission will be rejected.

In guided agent flows, check module permissions before offering destructive actions to the user. This avoids walking the user through a flow that their account cannot complete.

Error and re-authentication shape

All AgentX tools may return an error object instead of the normal success payload when the session is invalid or an operation fails:

{
  "error": true,
  "message": "Session expired",
  "authUrl": "https://www.alphaladder.hk/..."
}

Field	Type	Description
`error`	`true`	Literal — always present on error responses
`message`	string	Human-readable error description
`authUrl`	string (optional)	Re-authentication URL; present when the session has expired and the user must log in again

When authUrl is present, direct the user to that URL to re-authenticate, then retry the operation.

For OTC-specific errors (HTTP 410 / 409), see the Response Reference.