Wallet History

Get 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

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