MCP Tools
Complete parameter and return reference for all 25 fiat-only AgentX MCP tools across payments (accounts, OTC exchange, fiat deposit, withdrawal, history) and fixed income.
All tools are available via the Alpha Ladder MCP server at https://www.alphaladder.hk/mcp. Check module permissions before calling any module-specific tool. Cross-cutting concepts (minor units, withdrawalParty, fee enums, verification codes) are defined in Concepts.
Accounts
get_account_summary
Get a USD-equivalent balance summary across all product account categories. Read-only.
Parameters
None.
Returns
An object with keys fiat, investment_fiat, quarantine_portfolio, investment_product. Each key maps to { availableAmount, pendingAmount, totalAmount } — all high-precision USD decimal strings.
get_account_detail
Fetch per-currency breakdown for a specific product account. Read-only.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
productCode | string (enum) | yes | fiat | investment_fiat | quarantine_portfolio | investment_product | named_account |
Returns
On success: { data: { holderCode, productCode, availableAmount, pendingAmount, totalAmount, instrumentInfoMap } }. instrumentInfoMap is keyed by currency code; each entry has availableAmount, availableAmountDisplay, pendingAmount, pendingCreditAmount. On session expiry: { error: true, message, authUrl? }. See Accounts & Balances.
get_module_permissions
Check which financial modules the authenticated user can access. Read-only.
Parameters
None.
Returns
{ permissions: [{ module: 'deposit'|'otc'|'withdrawal'|'wealth', hasPermission: boolean }] }
get_available_currency_pairs
List all currency pairs available for OTC exchange. Read-only.
Parameters
None.
Returns
{ pairs: string[] } — each element is a tradeable pair in BASE/QUOTE format (e.g. "USD/EUR", "GBP/SGD").
OTC Exchange
Requires otc module permission. The OTC flow is two steps: get_otc_quote → confirm_otc_trade. For error handling (HTTP 410 / 409), see Response Reference.
get_exchange_quote
Fetch the current from→to exchange rate without locking a quote or checking balance. Use for browsing rates or pre-lock math. Read-only.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
fromCurrency | string | yes | Source currency code (e.g. "USD", "SGD") |
toCurrency | string | yes | Target currency code (e.g. "EUR", "GBP") |
Returns
{ rate: string } — the decimal from→to exchange rate. Multiply fromCurrency amount by rate to get the toCurrency amount. Does not lock a quote or reserve balance.
get_otc_quote
Step 1 of OTC exchange. Locks a quote at a specific amount and performs a backend balance and limit check. Read-only.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
fromCurrency | string | yes | Source currency code (e.g. "USD", "EUR") |
toCurrency | string | yes | Target currency code (e.g. "EUR", "SGD") |
totalValue | string | yes | Amount to exchange in source currency (e.g. "1000", "500.50") |
Returns
On success: { quoteCode, exchangeRate, finalAmount, validityPeriod, fromCurrency, toCurrency, totalValue, expiry }. On failure: { success: false, message }.
| Field | Type | Description |
|---|---|---|
quoteCode | string | Pass unchanged to confirm_otc_trade |
exchangeRate | string | Locked from→to rate. May be "" when pricing is unavailable — do not proceed to confirm in that case |
finalAmount | string | Estimated receive amount in toCurrency. May be "" when pricing is unavailable |
validityPeriod | number | Seconds the user has to confirm (UX hint; the server keeps context for 5 minutes) |
expiry | string | Absolute expiry timestamp (ISO 8601 UTC) |
Always display exchangeRate and finalAmount to the user before calling confirm_otc_trade.
confirm_otc_trade
Step 2 of OTC exchange. Executes the trade at the live rate.
The server re-fetches a fresh rate at confirm time; the executed exchangeRate and finalAmount in this response are the final settled values and may differ from the get_otc_quote values. Failures are HTTP errors: 410 = quote context expired; 409 = rate drift exceeded. On either error, do not auto-retry — call get_otc_quote again.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
quoteCode | string | yes | quoteCode returned by get_otc_quote |
Returns
{ id, tradeCode, point, exchangeRate?, finalAmount? }
| Field | Type | Description |
|---|---|---|
id | number | Internal trade record ID |
tradeCode | string | Transaction reference code — show as the trade identifier |
point | string | Loyalty/reward points earned (decimal string) |
exchangeRate | string (optional) | Actual executed exchange rate |
finalAmount | string (optional) | Actual amount received in toCurrency |
get_otc_trade_detail
Look up the full detail of a settled or pending OTC trade by its tradeCode. Read-only.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
tradeCode | string | yes | OTC trade code (e.g. the code returned by confirm_otc_trade) |
Returns
{ trade: object | null } — null when no trade matches the code.
trade fields:
| Field | Type | Description |
|---|---|---|
tradeCode | string | Unique OTC trade code |
tradeStatus | number | Status code (e.g. 1 = pending, 4 = settled) |
tradingAction | number | 1 = buy base, 2 = sell base |
buyerCode | string | Buyer participant code |
buyerName | string | Buyer display name |
sellerCode | string | Seller participant code |
sellerName | string | Seller display name |
baseCurrency | string | Base currency code |
quoteCurrency | string | Quote currency code |
baseQuantity | string | Quantity of base currency |
quoteAmount | string | Amount of quote currency exchanged |
quotePrice | string | Quoted rate before adjustments |
finalPrice | string | Final locked exchange rate |
tradeTime | string | Trade creation timestamp (ISO 8601) |
settleTime | string | Scheduled settlement timestamp (ISO 8601) |
updatedTime | string | Last status update timestamp (ISO 8601) |
Fiat Deposit
Requires deposit module permission.
get_fiat_deposit_currencies
List fiat currencies available for deposit. Read-only.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
withdrawalParty | string (enum) | no | 'first_party' or 'third_party'. Defaults to first-party |
isSameNameAccount | boolean | no | true for named-account (same-name) deposit flow |
Returns
{ currencies: string[] } — available fiat currency codes (e.g. "USD", "EUR", "GBP").
get_deposit_bank_account
Get Alpha Ladder's bank account details for a given currency (where to wire funds). Read-only.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
currency | string | yes | Fiat currency code (e.g. "USD", "EUR", "GBP") |
Returns
{ accounts: [{ ownerName, ownerAddress, ownerCountryCode, baNumber, swiftCode, bankName, bankAddress, countryCode }] } — Alpha Ladder's receiving bank account details.
get_fiat_deposit_bank_accounts
List payor bank accounts available for fiat deposit. Read-only.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
withdrawalParty | string (enum) | yes | 'first_party' or 'third_party' |
Returns
{ accounts: [{ baNumber, ownerName, ownerAddress?, ownerCountryCode?, swiftCode?, bankName?, bankAddress?, countryCode?, ownerType?, relationship?, ownerCorporateCountryCode?, baTag?, relationType? }] } — payor bank accounts (own accounts for first-party; registered COBO payors for third-party).
get_third_party_fiat_deposit_estimate
Estimate a third-party (COBO) fiat deposit — fee calculation and bank account details. Read-only.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
currency | string | yes | Fiat currency code (e.g. "USD") |
amount | string | yes | Deposit amount as positive decimal string |
feePayer | string (enum) | yes | 'paid_by_me' or 'paid_by_third_party' |
baNumber | string | yes | Payor bank account number — must be from get_fiat_deposit_bank_accounts |
isSameNameAccount | boolean | no | true for named-account flow |
Returns
{ accountType: 'fiat', depositType, amountSent, estimatedServiceFee, estimatedAmountReceived, payorBankAccount, receiverBankAccount }. Show fee and amounts to the user for confirmation before calling execute_third_party_fiat_deposit_submit.
execute_third_party_fiat_deposit_submit
Submit a third-party (COBO) fiat deposit request.
Call get_third_party_fiat_deposit_estimate first and confirm fee/amounts with the user before calling this tool.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
currency | string | yes | Fiat currency code (e.g. "USD") |
amount | string | yes | Deposit amount as positive decimal string |
feePayer | string (enum) | yes | 'paid_by_me' or 'paid_by_third_party' |
baNumber | string | yes | Payor bank account number (from get_fiat_deposit_bank_accounts) |
isSameNameAccount | boolean | no | true for named-account flow |
Returns
{ depositNumber: string } — the deposit requirement number (e.g. "DP2026...").
get_named_account_currencies
List fiat currencies supported for same-name (named) account transfers. Read-only.
Parameters
None.
Returns
{ currencies: string[] } — currency codes supporting named-account deposits (e.g. "SGD", "EUR", "USD").
get_named_account_list
Get the user's registered same-name (named) bank accounts for first-party fiat transfers. Read-only.
Parameters
None.
Returns
{ accounts: [{ baNumber, ownerName, ownerAddress?, ownerCountryCode?, swiftCode?, bankName?, bankAddress?, countryCode?, ... }] } — the user's bound same-name bank account details. Call get_named_account_currencies first to confirm the selected currency supports named-account transfers.
Withdrawal
Requires withdrawal module permission. Always call get_withdrawal_quote before executing to confirm service fee and minimum amount. For third-party withdrawals, purposeOfTransaction is required on execute calls.
get_withdrawal_currencies
List fiat currencies available for withdrawal. Read-only.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
currencyType | 1 (integer literal) | yes | 1 = fiat (the only supported asset class) |
withdrawalParty | 1 or 2 (integer literal) | yes | 1 = first-party, 2 = third-party |
isSameNameAccount | boolean | no | true = same-name account path |
Returns
{ currencies: string[] } — fiat currency codes available for withdrawal.
get_withdrawal_quote
Get the service fee and minimum withdrawal amount in a single call. Read-only.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
withdrawalParty | 1 or 2 (integer literal) | yes | 1 = first-party, 2 = third-party |
currency | string | yes | Uppercase alphanumeric currency code |
amount | string | yes | Withdrawal amount as positive decimal string |
isSameNameAccount | boolean | no | Fiat only |
Returns
{ fee: { serviceFee: string }, minimumAmount: { minimumAmount: number } }.
get_fiat_withdrawal_bank_accounts
List non-same-name fiat withdrawal bank accounts (regular bound accounts). Read-only.
Parameters
None.
Returns
{ accounts: [{ baNumber, ownerName, ownerAddress?, ownerCountryCode?, swiftCode?, bankName?, bankAddress?, countryCode?, ownerType?, ... }] }. For same-name accounts, use get_named_account_list instead.
execute_fiat_withdrawal
Execute a fiat withdrawal.
Confirm fee and minimum with get_withdrawal_quote and confirm the destination bank account with the user before calling this tool.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
withdrawalParty | 1 or 2 (integer literal) | yes | 1 = first-party, 2 = third-party |
currency | string | yes | Uppercase alphabetic fiat currency code |
amount | string | yes | Withdrawal amount as positive decimal string |
bankAccountNumber | string | yes | Destination bank account number |
verificationCode | string | yes | One-time verification code from Alpha Ladder authentication |
chargeType | integer (1–3) | no | 1 = beneficiary bears fee, 2 = sender bears fee, 3 = shared |
isSameNameAccount | boolean | no | true for same-name account path (fiat only) |
purposeOfTransaction | string | conditional | Required when withdrawalParty = 2 (third-party) |
Returns
{ txCode, currency, status, withdrawalAmount?, chargeAmount?, totalChargeAmount?, amountReceived?, to?, createAt?, updateAt? }. See Response Reference.
History
get_deposit_list
Query paginated deposit transaction records. Read-only.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
pageNum | integer ≥ 1 | yes | Page number, starting from 1 |
pageSize | integer 1–100 | yes | Records per page (max 100) |
payeeAccountType | number | yes | 1 = fiat deposits |
startTime | string | no | Start of time range: "YYYY-MM-DD HH:mm:ss" |
endTime | string | no | End of time range: "YYYY-MM-DD HH:mm:ss" |
Returns
{ total, list, pageNum, pageSize, pages }. Each list item: { paymentCode, status, statusDesc, currency, totalAmount, receiveAmount, chargeAmount, detail, createAt, updateAt, payerCode, payerName, payeeCode, payeeName, coboInfo, ... }.
Amounts (totalAmount, receiveAmount, chargeAmount) are integers in minor units — divide by 10^decimals. See Response Reference.
get_withdrawal_list
Query paginated withdrawal transaction records. Read-only.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
pageNum | integer ≥ 1 | yes | Page number, starting from 1 |
pageSize | integer 1–100 | yes | Records per page (max 100) |
payeeAccountType | number | yes | 1 = fiat withdrawals |
startTime | string | no | Start of time range: "YYYY-MM-DD HH:mm:ss" |
endTime | string | no | End of time range: "YYYY-MM-DD HH:mm:ss" |
Returns
{ total, list, pageNum, pageSize, pages }. Each list item: { paymentCode, status, statusDesc, currency, totalAmount, receiveAmount, chargeAmount, paymentType, purposeOfTransaction, pathTo, fee, feeRate, detail, createAt, updateAt, coboInfo, poboInfo, ... }.
paymentType: 21 = first-party, 22 = third-party. Amounts are integers in minor units — divide by 10^decimals. See Response Reference.
Fixed Income
Requires wealth module permission. Always call investor_precheck before fip_subscribe to verify required agreements are signed.
get_fip_products
Query available Alpha Ladder Wealth Fixed Income Products. Read-only.
Parameters
None.
Returns
{ success, code, msg, data, currencyConvertInfoList? }
data is an array of products:
| Field | Type | Description |
|---|---|---|
productCode | string | Internal product code |
productName | string | Display name |
productType | string | Category (currently FIP) |
term | string | Human-readable term (e.g. "Flexible", "30 Days") |
termType | integer | 1 = flexible/open term, 2 = fixed term |
sort | integer | Sort order |
estApr | string | Estimated APR or range (percentage string) |
currencyItemList | array | Supported currency options (see below) |
Each currencyItemList entry:
| Field | Type | Description |
|---|---|---|
id | string | Currency item unique identifier — pass to fip_subscribe |
currency | string | Currency code (e.g. "USD", "EUR", "SGD") |
estApr | string | APR for this currency option |
term | string | Human-readable term |
termType | integer | 1 = flexible, 2 = fixed |
termDays | integer | Term in days; negative values indicate flexible settlement products |
liquidity | string | Settlement description (e.g. "(T + 1 Settlement)") |
mhp | string | Minimum holding period description; empty string if not specified |
issuer | string | Issuer name |
get_fip_agreement
Query FIP agreement documents (PDF links) for a specific product and currency. Read-only.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
productType | string | yes | Product category (e.g. "FIP") |
productCode | string | yes | Product code (e.g. "FIP_OpenTerm_T+1", "FIP_30Days") |
currency | string | yes | Currency code (e.g. "USD", "EUR", "SGD") |
Returns
{ agreements: [{ product_type, product_code, currency, url, show_name, sort, term_days }] }. url is a PDF download link. Present the agreement document to the user before subscribing.
investor_precheck
Check whether the user has completed required investor agreements and declarations. Read-only.
Parameters
None.
Returns
{
"Master Brokerage Agreement & Trading Rules": true,
"investorDeclarationTag": false
}| Field | Type | Description |
|---|---|---|
Master Brokerage Agreement & Trading Rules | boolean | Whether the Master Brokerage Agreement has been signed |
investorDeclarationTag | boolean | Whether the investor declaration has been completed |
If either field is false, the user must complete that step before subscribing to a FIP product.
fip_subscribe
Subscribe to a Alpha Ladder Wealth Fixed Income Product.
Call investor_precheck and present the get_fip_agreement document to the user before calling this tool.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Currency item ID from get_fip_products (currencyItemList[].id) |
currency | string | yes | Currency code (e.g. "USD", "EUR", "SGD") |
termDays | integer | yes | Term length in days. Use negative values for flexible products (e.g. -2 for T+1 settlement, -1 for T+3) |
subscriptionAmount | number | yes | Subscription amount in the specified currency |
Returns
{ success, code, msg, data, currencyConvertInfoList? }
data fields:
| Field | Type | Description |
|---|---|---|
currency | string | Subscribed currency |
subscriptionAmount | string | Confirmed subscription amount |
subscriptionDate | string or null | Subscription date (e.g. "2026-04-09"); null if not yet determined |
returnsAccrualStartDate | string or null | Date returns start accruing; null if not yet determined |
initialRedemptionOpeningDay | string or null | Earliest redemption date; null if not yet determined |
settlementDate | string or null | Settlement date; null if not yet determined |
Transaction History
Query paginated deposit and withdrawal history for your Alpha Ladder account, with time-range filtering and per-record status details.
Response Reference
Shared response conventions for AgentX MCP tools — minor units, status fields, OTC trade codes, re-authentication shape, and OTC two-step error model.