# Search Users

Find users by username — the primary lookup for peer-to-peer payment flows.

## Overview

This endpoint performs a username-prefix search and returns matching users along with their wallets, making it ideal for a "Send to" screen where the sender types a recipient's username. The response includes wallet addresses directly, so you can pre-populate a payment form without a separate wallet lookup call.

Results are ordered by match relevance. The search is case-insensitive and matches from the start of the username.

> 💡 Debounce this call on the client side (300–500ms) to avoid firing on every keystroke. Only search when at least 2 characters have been entered.

### `GET /v1/users/search`

Authentication: bearer token required.

Returns users whose username matches the query string, with their wallet info.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `username` | string | yes | Username prefix to search (min 1 character) |

**Responses**

`200` OK

```json
[
  {
    "id": "uuid",
    "username": "alice",
    "qrCode": "data:image/png;base64,...",
    "wallets": [
      { "id": "wallet-uuid", "chain": "ethereum", "address": "0x...", "isPrimary": true }
    ]
  }
]
```

## Implementation

```javascript
// Debounced username search for a "Send to" input field
function debounce(fn, ms) {
  let timer;
  return (...args) => {
    clearTimeout(timer);
    timer = setTimeout(() => fn(...args), ms);
  };
}

async function searchUsers(token, query) {
  if (query.length < 2) return [];

  const res = await fetch(
    `https://api.aureahub.com/v1/users/search?username=${encodeURIComponent(query)}`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  return res.json(); // Array of { id, username, qrCode, wallets }
}

// Attach to an input field with debouncing
const searchInput = document.getElementById('recipient-search');
const debouncedSearch = debounce(async (e) => {
  const results = await searchUsers(accessToken, e.target.value);
  renderRecipientList(results);
}, 350);

searchInput.addEventListener('input', debouncedSearch);
```

---

Web version: https://docs.aureahub.com/#users-search