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.

This page documents the response conventions shared across all AgentX tools. For tool-specific return shapes, see MCP Tools. For status code and error-handling reference, see also Status & Errors.

Minor units in history lists

The get_deposit_list and get_withdrawal_list tools return monetary amounts as integers in minor units, not as decimal strings.

Rule: divide by 10^decimals before displaying.

Field	Tool	Units
`totalAmount`	`get_deposit_list`, `get_withdrawal_list`	Minor units (integer)
`receiveAmount`	`get_deposit_list`, `get_withdrawal_list`	Minor units (integer)
`chargeAmount`	`get_deposit_list`, `get_withdrawal_list`	Minor units (integer)
`totalChargeAmount`	`get_withdrawal_list`	Minor units (integer)
`deductibleAmount`	`get_withdrawal_list`	Minor units (integer)

Example: totalAmount: 150025 for USD = $1,500.25 (USD has 2 decimal places).

All other tools — account detail, execute tools, quote tools — use decimal strings (e.g. "1500.25") and require no conversion.

Deposit records — key status fields

Each record in get_deposit_list carries:

Field	Type	Description
`paymentCode`	string	Unique deposit reference (e.g. `"DP2026040110300001"`)
`status`	number	Deposit status code
`statusDesc`	string or null	Human-readable status; may be `null` while the status-code mapping is pending — display the raw `status` with a note when `null`
`currency`	string	Deposit currency code
`detail`	string or null	Additional deposit detail; usually `null` for fiat deposits

Withdrawal records — key status fields

Each record in get_withdrawal_list carries:

Field	Type	Description
`paymentCode`	string	Unique withdrawal reference (e.g. `"WD2026042709550001"`)
`status`	number	Withdrawal status code
`statusDesc`	string or null	Human-readable status; may be `null` — display raw `status` with a note when `null`
`currency`	string	Withdrawal currency code
`paymentType`	number	`21` = first-party, `22` = third-party
`purposeOfTransaction`	string or null	Purpose field; meaningful for `paymentType = 22` (third-party) only
`pathTo`	string or null	Destination route, e.g. `"BANK"`

Execute withdrawal response

execute_fiat_withdrawal returns:

Field	Type	Description
`txCode`	string	Unique transaction tracking code (e.g. `"WD2026041121000001"`)
`currency`	string	Currency code of the withdrawal
`status`	number	Initial withdrawal status (e.g. `13` = fiat pending)
`withdrawalAmount`	string (optional)	Original amount requested
`chargeAmount`	string (optional)	Service fee charged
`totalChargeAmount`	string (optional)	Total charges including service fee
`amountReceived`	string (optional)	Net amount the beneficiary receives after fees
`to`	string (optional)	Destination bank account number
`createAt`	string (optional)	Creation timestamp
`updateAt`	string (optional)	Last status update timestamp

OTC trade codes

The OTC two-step flow returns identifiers at each step:

Field	Source tool	Description
`quoteCode`	`get_otc_quote`	Identifies the locked quote; pass unchanged to `confirm_otc_trade`
`tradeCode`	`confirm_otc_trade`	Unique trade reference (e.g. `"OT2026043015320000"`); use as the user-facing transaction ID

After confirming, use get_otc_trade_detail with the tradeCode to retrieve full settlement details (final rate, settlement timestamps, buyer/seller codes).

Re-authentication error shape

When a session has expired or authentication is required, tools return this object instead of the normal success payload:

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

Field	Type	Description
`error`	`true` (literal)	Always present on error responses
`message`	string	Human-readable description of the error
`authUrl`	string (optional)	Re-authentication URL; present when the user must log in again

When authUrl is present, redirect the user to that URL. After successful authentication, retry the original tool call.

OTC two-step error model

The confirm_otc_trade tool surfaces OTC failures as HTTP errors, not as { success: false } payloads:

HTTP status	Meaning	Action
`410 Gone`	Quote context expired — the 5-minute server window elapsed	Inform the user; call `get_otc_quote` again to obtain a fresh quote
`409 Conflict`	Live rate drifted beyond the system drift tolerance from the originally quoted rate	Inform the user of the rate change; call `get_otc_quote` again so they can review the new rate before confirming

Do not auto-retry on either error. The user must explicitly review the new quote before proceeding.

The get_otc_quote response may also indicate rate unavailability: if exchangeRate or finalAmount is an empty string (""), the downstream pricing service cannot price this pair at that moment. Do not proceed to confirm_otc_trade — inform the user and let them retry or pick a different pair.

For general status code and error handling, see Status & Errors.