# 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](/developers/financial-services/tools). For status code and error-handling reference, see also [Status & Errors](/developers/reference/status-and-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:

```json
{
  "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](/developers/reference/status-and-errors).