> For the complete documentation index, see [llms.txt](https://onchainlabs-tech-documentation.gitbook.io/wallettwo-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onchainlabs-tech-documentation.gitbook.io/wallettwo-documentation/api/wallet-history.md).

# Wallet History

GET <https://api.wallettwo.com/blockchain/v1/api/wallet/history>

```

### Authentication

This endpoint is authenticated with an API key. Pass it in the `x-api-key` header.

```

x-api-key: \<YOUR\_API\_KEY>

```

If the header is missing or the key fails verification against the WalletTwo auth service, the request is rejected.

### Query parameters

| Name      | Type             | Required | Description                                                                            |
| --------- | ---------------- | -------- | -------------------------------------------------------------------------------------- |
| `address` | string           | Yes      | Wallet address whose history is requested.                                             |
| `chainId` | string \| number | Yes      | Decimal chain ID of the network. Must match a network registered in the database.      |
| `cursor`  | string           | No       | Pagination cursor returned by a previous response. Omit for the first page.            |
| `order`   | string           | No       | Sort order. `DESC` (default) returns newest first; `ASC` returns oldest first.         |
| `limit`   | integer          | No       | Maximum number of records to return. Defaults to `100`.                                |

### Example requests

First page:

```

curl -X GET "<https://api.wallettwo.com/blockchain/v1/api/wallet/history?address=0xabc...&chainId=1>"\
-H "x-api-key: $WALLETTWO\_API\_KEY"

```

Next page (using a cursor from a previous response):

```

curl -X GET "<https://api.wallettwo.com/blockchain/v1/api/wallet/history?address=0xabc...&chainId=1&cursor=eyJhbGci...&limit=50>"\
-H "x-api-key: $WALLETTWO\_API\_KEY"

```

Ascending order with custom page size:

```

curl -X GET "<https://api.wallettwo.com/blockchain/v1/api/wallet/history?address=0xabc...&chainId=137&order=ASC&limit=25>"\
-H "x-api-key: $WALLETTWO\_API\_KEY"

### Example response

```json
{
  "history": {
    "cursor": "eyJhbGciOiJIUzI1NiJ9...",
    "page": 0,
    "page_size": 100,
    "limit": "100",
    "result": [
      {
        "hash": "0x9a1b...c8d2",
        "nonce": "42",
        "transaction_index": "12",
        "from_address": "0xabc...",
        "to_address": "0xdef...",
        "value": "1000000000000000000",
        "gas": "21000",
        "gas_price": "20000000000",
        "receipt_status": "1",
        "block_timestamp": "2025-09-12T14:32:11.000Z",
        "block_number": "20912345",
        "block_hash": "0xb1...e4",
        "category": "send",
        "summary": "Sent 1 ETH to 0xdef...",
        "native_transfers": [],
        "erc20_transfers": [],
        "nft_transfers": []
      }
    ]
  }
}
```

The exact item shape is produced by `wallets/{address}/history` endpoint. Fields such as `native_transfers`, `erc20_transfers`, and `nft_transfers` are populated when the transaction includes the corresponding asset movements.

#### Pagination

Use the `cursor` value from a response to request the next page. When the response returns no `cursor` (or an empty one), there are no more results.

#### Errors

| Status | Reason                                                               |
| ------ | -------------------------------------------------------------------- |
| 400    | `Address is required` — missing `address` query param.               |
| 400    | `Network ID is required` — missing `chainId` query param.            |
| 400    | `Network with chainId <id> not found` — `chainId` is not registered. |
| 401    | `x-api-key` header missing.                                          |
| 401    | `Invalid API key.` — key failed upstream verification.               |
| 502    | `Failed to fetch wallet history.` — upstream call failed.            |

#### Notes

* Responses are not cached at the API layer; rate limits and freshness follow the upstream provider.
* The endpoint resolves the network by `chainId` and converts it to the hex chain identifier  — callers always pass the decimal `chainId`.