> For the complete documentation index, see [llms.txt](https://sodex.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sodex.com/documentation/for-developers/api-reference/mirror-api/history-and-status.md).

# History & Status

Use the history endpoint for account-level reconciliation and the status endpoints to locate a transfer by its external or ValueChain identifier.

## Deposit and withdrawal history

`GET /user/{userAddress}/deposit-withdrawals`

```bash
curl "https://mainnet-gw.sodex.dev/api/v1/user/0x1111111111111111111111111111111111111111/deposit-withdrawals?side=withdraw&pending=true&limit=10" \
  -H "Accept: application/json"
```

### Query parameters

| Name         | Type    | Required | Description                               |
| ------------ | ------- | -------- | ----------------------------------------- |
| `start`      | int32   | No       | Pagination offset. Minimum `0`.           |
| `startTime`  | int64   | No       | Start-time filter. Minimum `0`.           |
| `endTime`    | int64   | No       | End-time filter. Minimum `0`.             |
| `limit`      | int32   | No       | Page size from `1` to `10`; default `10`. |
| `side`       | string  | No       | `deposit` or `withdraw`.                  |
| `token`      | string  | No       | Token identifier or address.              |
| `pending`    | boolean | No       | Select pending or non-pending records.    |
| `chain`      | string  | No       | External chain identifier.                |
| `coinSymbol` | string  | No       | Coin symbol.                              |

`data.records` contains the current page and `data.total` contains the total number of matches. A record includes account, amount, coin, chain, decimals, sender, receiver, status, timestamps, token, and current transaction hash. It can also include `originTxHash`, `withdrawFee`, `withdrawId`, `failCode`, and `failReason`.

## Transfer status endpoints

These APIs return external deposit or withdrawal records that match a transfer identifier.

## Deposit status

Return deposit records for an external-chain transaction hash.

### Request

```http
GET /api/v1/user/deposit/status
```

### Query Parameters

| Name     | Type     | Required | Description                              |
| -------- | -------- | -------- | ---------------------------------------- |
| `chain`  | `string` | `true`   | External chain identifier.               |
| `txHash` | `string` | `true`   | External-chain deposit transaction hash. |

### Request Example

```bash
curl \
  "https://mainnet-gw.sodex.dev/api/v1/user/deposit/status?chain=BASE_ETH&txHash=0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Accept: application/json"
```

Additional Information:

* The same deposit transaction hash may match multiple records with different `n` values.
* If `chain` does not match the record, the API returns an empty result instead of an error.

## Withdrawal status

Return withdrawal records by withdrawal ID or by the ValueChain transaction hash of the withdrawal request.

### Request

```http
GET /api/v1/user/withdraw/status
```

### Query Parameters

| Name         | Type     | Required | Description                                                                                   |
| ------------ | -------- | -------- | --------------------------------------------------------------------------------------------- |
| `chain`      | `string` | `true`   | External chain identifier.                                                                    |
| `withdrawId` | `string` | `false`  | Withdrawal request identifier. Required when `txHash` is omitted.                             |
| `txHash`     | `string` | `false`  | ValueChain transaction hash of the withdrawal request. Required when `withdrawId` is omitted. |

### Request Examples

Query by withdrawal ID:

```bash
curl \
  "https://mainnet-gw.sodex.dev/api/v1/user/withdraw/status?chain=BASE_ETH&withdrawId=12345" \
  -H "Accept: application/json"
```

Query by the ValueChain withdrawal-request transaction hash:

```bash
curl \
  "https://mainnet-gw.sodex.dev/api/v1/user/withdraw/status?chain=BASE_ETH&txHash=0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" \
  -H "Accept: application/json"
```

Additional Information:

* At least one of `withdrawId` and `txHash` is required.
* Prefer `withdrawId`. When both parameters are provided, `withdrawId` takes precedence and `txHash` is ignored.
* `withdrawId` is forwarded unchanged. Clients must not assume that it is always numeric.
* The `txHash` fallback accepts only the ValueChain transaction hash of the withdrawal request. It cannot query by the final external-chain withdrawal transaction hash.
* If `chain` does not match the record, the API returns an empty result instead of an error.

## Response

Both APIs use the same response schema.

| Name        | Type                       | Required | Description                              |
| ----------- | -------------------------- | -------- | ---------------------------------------- |
| `code`      | `int32`                    | `true`   | Response status code. `0` means success. |
| `data`      | `DepositWithdrawalHistory` | `true`   | Matching deposit or withdrawal records.  |
| `timestamp` | `uint64`                   | `true`   | Response timestamp in milliseconds.      |

### DepositWithdrawalHistory

| Name      | Type                        | Required | Description                             |
| --------- | --------------------------- | -------- | --------------------------------------- |
| `records` | `DepositWithdrawalRecord[]` | `true`   | Matching deposit or withdrawal records. |
| `total`   | `int32`                     | `true`   | Total number of matching records.       |

### DepositWithdrawalRecord

| Name           | Type     | Required | Description                                          |
| -------------- | -------- | -------- | ---------------------------------------------------- |
| `account`      | `string` | `true`   | Sodex user account address.                          |
| `amount`       | `string` | `true`   | Transfer amount.                                     |
| `chain`        | `string` | `true`   | External chain identifier.                           |
| `coin`         | `string` | `true`   | Coin symbol.                                         |
| `decimals`     | `uint8`  | `true`   | Coin decimals.                                       |
| `failCode`     | `string` | `true`   | Failure code. Empty when no failure occurred.        |
| `failReason`   | `string` | `true`   | Failure reason. Empty when no failure occurred.      |
| `n`            | `string` | `true`   | Mirror record sequence or cursor value.              |
| `receiver`     | `string` | `true`   | Receiving address.                                   |
| `reportAmount` | `string` | `true`   | Amount reported by the external transfer system.     |
| `sender`       | `string` | `true`   | Sending address.                                     |
| `status`       | `string` | `true`   | Current transfer status.                             |
| `statusTime`   | `int64`  | `true`   | Time when the status was last updated.               |
| `stmp`         | `int64`  | `true`   | Record timestamp.                                    |
| `token`        | `string` | `true`   | Token identifier or contract address.                |
| `txHash`       | `string` | `true`   | Current transaction hash.                            |
| `originTxHash` | `string` | `false`  | Original transaction hash. Omitted when unavailable. |
| `type`         | `string` | `true`   | Record type.                                         |
| `withdrawFee`  | `string` | `false`  | Withdrawal fee. Omitted when not applicable.         |
| `withdrawId`   | `uint64` | `false`  | Withdrawal identifier. Omitted when unavailable.     |

## Response Example

```json
{
  "code": 0,
  "timestamp": 1780000000000,
  "data": {
    "records": [
      {
        "account": "0x1111111111111111111111111111111111111111",
        "amount": "10000000",
        "chain": "BASE_ETH",
        "coin": "USDC",
        "decimals": 6,
        "failCode": "",
        "failReason": "",
        "n": "123456",
        "receiver": "0x2222222222222222222222222222222222222222",
        "reportAmount": "10000000",
        "sender": "0x1111111111111111111111111111111111111111",
        "status": "Processing",
        "statusTime": 1780000000,
        "stmp": 1780000000,
        "token": "0x3333333333333333333333333333333333333333",
        "txHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "originTxHash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
        "type": "withdraw",
        "withdrawFee": "1000000",
        "withdrawId": 123
      }
    ],
    "total": 1
  }
}
```

## Empty Response Example

No matching record is a successful response:

```json
{
  "code": 0,
  "timestamp": 1780000000000,
  "data": {
    "records": [],
    "total": 0
  }
}
```