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

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

Response – Premium PayID (Reserved)

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

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

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

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

{
  "success": true,
  "message": "Found 1 PayID(s)",
  "data": {
    "results": [
      {
        "id": "payid-id",
        "name": "username",
        "userId": "user-id",
        "email": "[e-mail]",
        "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

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

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

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

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