# Aggregation API

#### GET /wallets

Returns all wallets linked to a user, with balance and connection metadata.

http

```http
GET /wallets?user_id=usr_01J2K...
Authorization: Bearer sk_live_xxxx
```

**Query parameters**

| Parameter | Type   | Description                                                              |
| --------- | ------ | ------------------------------------------------------------------------ |
| `user_id` | string | Required. The Rupi user ID.                                              |
| `network` | string | Optional. Filter by network (`ethereum`, `polygon`, `base`, `arbitrum`). |

**Response**

json

```json
{
  "wallets": [
    {
      "id": "wlt_7TnQ...",
      "connection_id": "con_wallet_9KxP...",
      "address": "0xUser5678...EfGh",
      "network": "polygon",
      "usdc_balance": 3820.50,
      "usdt_balance": 0.00,
      "first_seen_block": 49823100,
      "created_at": "2024-12-01T10:01:00Z"
    }
  ]
}
```

#### GET /transactions

Returns normalized, filtered transactions for a user's connected wallets. Noise, wash trades, and circular flows are excluded by default.

http

```http
GET /transactions?user_id=usr_01J2K...
Authorization: Bearer sk_live_xxxx
```

**Query parameters**

| Parameter          | Type    | Description                                                                                           |
| ------------------ | ------- | ----------------------------------------------------------------------------------------------------- |
| `user_id`          | string  | Required.                                                                                             |
| `wallet_id`        | string  | Optional. Filter to a specific wallet.                                                                |
| `direction`        | string  | Optional. `inbound` or `outbound`.                                                                    |
| `classification`   | string  | Optional. One of `verified_income`, `p2p`, `dex_trade`, `unknown`.                                    |
| `token`            | string  | Optional. `USDC` or `USDT`.                                                                           |
| `from_date`        | string  | Optional. ISO 8601.                                                                                   |
| `to_date`          | string  | Optional. ISO 8601.                                                                                   |
| `include_filtered` | boolean | Optional. Default `false`. If `true`, includes wash trades and circular flows with their fraud flags. |
| `limit`            | integer | Optional. Default 50, max 200.                                                                        |
| `cursor`           | string  | Optional. Pagination cursor from previous response.                                                   |

**Response**

json

```json
{
  "transactions": [
    {
      "id": "txn_2VwR...",
      "wallet_id": "wlt_7TnQ...",
      "tx_hash": "0xabc123def456...",
      "block_number": 49830200,
      "block_timestamp": "2024-11-30T14:22:00Z",
      "direction": "inbound",
      "from_address": "0xDeel1234...AbCd",
      "to_address": "0xUser5678...EfGh",
      "token": "USDC",
      "amount": 4500.00,
      "network": "polygon",
      "classification": "verified_income",
      "fraud_flags": []
    },
    {
      "id": "txn_8BqS...",
      "wallet_id": "wlt_7TnQ...",
      "tx_hash": "0xdef789abc...",
      "block_number": 49831000,
      "block_timestamp": "2024-11-30T15:10:00Z",
      "direction": "inbound",
      "from_address": "0xFriend9900...XyZw",
      "to_address": "0xUser5678...EfGh",
      "token": "USDC",
      "amount": 200.00,
      "network": "polygon",
      "classification": "p2p",
      "fraud_flags": []
    }
  ],
  "pagination": {
    "cursor": "csr_next_abc...",
    "has_more": true
  }
}
```

**Filtering behavior**

By default, the `/transactions` endpoint applies all fraud filters before returning results. This means:

* Wash trades (`classification: wash_trade`) are excluded.
* Circular flows (`classification: circular`) are excluded.
* Transactions from unverified, non-whitelisted addresses that do not match any payroll record are returned with `classification: unknown` but are included.

Set `include_filtered=true` to retrieve all transactions including excluded ones, with `fraud_flags` populated to explain why each was flagged.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rupi.global/core-documentation/markdown/aggregation-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.