# 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](/developers/financial-services/accounts#get_module_permissions) before calling any module-specific tool. Cross-cutting concepts (minor units, `withdrawalParty`, fee enums, verification codes) are defined in [Concepts](/developers/financial-services/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](/developers/financial-services/accounts#get_account_detail).

---

### 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](/developers/financial-services/responses#otc-two-step-error-model).

### 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.

<Callout type="warn">Destructive — requires explicit user confirmation before calling.</Callout>

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.

<Callout type="warn">Destructive — requires explicit user confirmation before calling.</Callout>

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.

<Callout type="warn">Destructive — requires explicit user confirmation before calling.</Callout>

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](/developers/financial-services/responses#execute-withdrawal-response).

---

## 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](/developers/financial-services/responses#minor-units-in-history-lists).

---

### 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](/developers/financial-services/responses#minor-units-in-history-lists).

---

## 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**

```json
{
  "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.

<Callout type="warn">Destructive — requires explicit user confirmation before calling.</Callout>

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 |