> For the complete documentation index, see [llms.txt](https://docs.reveel.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.reveel.id/payids-old.md).

# PayIDs - old

### Parameter Reference

| Field            | Type    | Required     | Description                                             |
| ---------------- | ------- | ------------ | ------------------------------------------------------- |
| `userId`         | string  | Yes          | Unique ID of the user registering or checking a PayID   |
| `payId`          | string  | Yes          | Desired PayID username (case-insensitive, alphanumeric) |
| `expiresInYears` | number  | No           | For premium PayIDs: the number of years to reserve      |
| `q`              | string  | Yes (search) | Keyword to search PayIDs                                |
| `limit`          | number  | No           | Max number of search results (default: 10)              |
| `activeOnly`     | boolean | No           | Whether to return only active PayIDs (default: true)    |

***

### Authentication

All endpoints require authentication unless explicitly stated otherwise.

**Required Headers:**

```
Authorization: Bearer your-api-key
Content-Type: application/json
Accept: application/json
```

***

### 1. Register PayID

`POST /payid/claim`\
**Description:** Registers a free or premium PayID for a user.

#### Request Body

```json
{
  "userId": "user-id",
  "payId": "username",
  "expiresInYears": 1
}
```

#### Response – Premium PayID (Reserved)

```json
{
  "success": true,
  "message": "Premium PayID reserved for checkout",
  "data": {
    "payId": "username",
    "price": 10.0,
    "reservedUntil": "2023-01-01T00:30:00.000Z",
    "reservationId": "reservation-id",
    "checkoutUrl": "https://checkout.loop.markets/...",
    "loopItemId": "item-id"
  }
}
```

#### Response – Free PayID (Claimed)

```json
{
  "success": true,
  "message": "PayID claimed successfully",
  "data": {
    "payId": "username",
    "price": 0,
    "expiresAt": null,
    "transactionId": "transaction-id"
  }
}
```

#### Error Responses

| HTTP Code                   | Description                      |
| --------------------------- | -------------------------------- |
| `400 Bad Request`           | Missing or invalid fields        |
| `409 Conflict`              | PayID already claimed            |
| `500 Internal Server Error` | General server or Loop API issue |

```json
{
  "success": false,
  "message": "Invalid request data",
  "error": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "undefined",
      "path": ["userId"],
      "message": "userId is required"
    }
  ]
}
```

***

### 2. Get PayID Price

`GET /payid/check-price`\
**Description:** Returns the current price for a given PayID using AI scoring.

#### Query Parameters

* `userId` (required)
* `payId` (required)

#### Success Response

```json
{
  "success": true,
  "message": "PayID price calculated successfully",
  "data": {
    "payId": "username",
    "price": 10.0,
    "score": 0.85,
    "cached": true
  }
}
```

#### Error Responses

| HTTP Code                   | Description                 |
| --------------------------- | --------------------------- |
| `400 Bad Request`           | Missing or malformed fields |
| `409 Conflict`              | PayID already taken         |
| `500 Internal Server Error` | Price check failure         |

***

### 3. Search PayIDs

`GET /payid/search`\
**Description:** Searches Reveel's database for PayIDs by keyword.

#### Query Parameters

* `q` (required): Search term
* `limit` (optional): Max number of results (default: 10)
* `activeOnly` (optional): Only return active PayIDs (default: true)

#### Success Response

```json
{
  "success": true,
  "message": "Found 1 PayID(s)",
  "data": {
    "results": [
      {
        "id": "payid-id",
        "name": "username",
        "userId": "user-id",
        "email": "user@example.com",
        "twitterUsername": "username",
        "walletAddress": "0x..."
      }
    ],
    "count": 1
  }
}
```

#### Error Responses

| HTTP Code                   | Description                      |
| --------------------------- | -------------------------------- |
| `400 Bad Request`           | Invalid or missing `q` parameter |
| `500 Internal Server Error` | Search error                     |

```json
{
  "success": false,
  "message": "Invalid search parameters",
  "error": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "undefined",
      "path": ["q"],
      "message": "Search query is required"
    }
  ]
}
```

***

### 4. Premium PayID Purchase Webhook (Loop)

`POST /payid/loop-webhook`\
**Description:** Receives webhook events from Loop on premium PayID purchases.

#### Request Body

```json
{
  "agreementId": "agreement-id",
  "event": "TransferCreated",
  "itemId": "item-id",
  "invoiceId": "invoice-id",
  "networkName": "ethereum",
  "networkId": "1",
  "tokenSymbol": "USDC",
  "transferId": "transfer-id",
  "refId": "reservation-id"
}
```

#### Success Response

```json
{
  "success": true,
  "message": "received event TransferCreated"
}
```

#### Error Responses

| HTTP Code                   | Description               |
| --------------------------- | ------------------------- |
| `400 Bad Request`           | Invalid or missing fields |
| `404 Not Found`             | Reservation ID not found  |
| `500 Internal Server Error` | Failed to process webhook |

```json
{
  "success": false,
  "message": "Reservation not found",
  "error": "Reservation with ID reservation-id not found"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.reveel.id/payids-old.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.