# Quickstart

## PayID API Quickstart Guide

This guide shows how to integrate PayID into your app using the live REST API, step by step. We'll register users, claim PayIDs, configure routing, and finally initiate signed on-chain payments — no SDK needed.

### Authentication & Headers

Every request to the API must include:

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

📌 **API Base URL**: `https://api.reveel.id/v1`

{% hint style="info" %} <mark style="color:red;">**API keys are provided manually upon approval via email request.**</mark>&#x20;

<mark style="color:red;">**Please send your request from company email to: <devs@r3vl.xyz>**</mark>
{% endhint %}

### Prerequisites

Make sure you have:

* A valid API key
* A tool like curl, Postman, or any HTTP client

### Step 1: Create a User

```bash
curl -X POST https://api.reveel.id/v1/users \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "twitterUsername": "alice123",
    "walletAddress": "0x123abc456def789ghi"
  }'
```

Response:

```json
{
  "success": true,
  "data": {
    "id": "user-id",
    "email": "alice@example.com",
    "walletAddress": "0x123abc456def789ghi",
    "twitterUsername": "alice123",
    "createdAt": "2023-07-15T12:30:45.000Z"
  },
  "meta": {
    "message": "User created successfully"
  }
}
```

### Step 2: Claim a PayID

```bash
curl -X POST https://api.reveel.id/v1/pay-ids/claim \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-id",
    "payId": "alice",
    "expiresInYears": 1
  }'
```

Response for free PayID:

```json
{
  "success": true,
  "data": {
    "payId": "alice",
    "price": 0,
    "transactionId": "tx-id"
  },
  "meta": {
    "message": "PayID claimed successfully"
  }
}
```

For premium PayIDs:

```json
{
  "success": true,
  "data": {
    "checkoutUrl": "https://checkout.loop.markets/...",
    "reservationId": "abc123"
  },
  "meta": {
    "message": "Premium PayID reserved for checkout"
  }
}
```

### Step 3: Create a Route

```bash
curl -X POST https://api.reveel.id/v1/routes \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-id",
    "name": "Default USDC Route",
    "incomingNetworks": ["ETH", "POL"],
    "incomingTokens": ["USDC"],
    "outgoingWallet": "0x789destination..."
  }'
```

Response:

```json
{
  "success": true,
  "data": {
    "id": "route-id",
    "name": "Default USDC Route",
    "incomingNetworks": ["ETH", "POL"],
    "incomingTokens": ["USDC"],
    "outgoingWallet": "0x789destination...",
    "userId": "user-id",
    "createdAt": "2023-07-15T12:35:22.000Z",
    "updatedAt": "2023-07-15T12:35:22.000Z"
  },
  "meta": {
    "message": "Route created successfully"
  }
}
```

### Step 4: Initiate and Sign a Transaction

#### a. Initialize transaction from backend

```bash
curl -X POST https://api.reveel.id/v1/transactions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "sender-user-id",
    "recipientPayId": "bob",
    "amount": 1.5,
    "token": "ETH",
    "network": "ETH",
    "message": "Payment for services"
  }'
```

Response:

```json
{
  "success": true,
  "data": {
    "amount": 1.5,
    "token": "ETH",
    "network": "ETH",
    "tx": {
      "to": "0xrecipient...",
      "data": "0x6572b...",
      "value": "1500000000000000000",
      "chainId": 1
    },
    "fees": {
      "applicationFee": null,
      "protocolFee": null,
      "bridgeFee": null
    }
  },
  "meta": {
    "message": "Transaction initialized successfully"
  }
}
```

**ERC20 Token Example (with approval)**

When sending ERC20 tokens, you may receive an `approveTx` that needs to be executed first:

```json
{
  "success": true,
  "data": {
    "amount": 10,
    "token": "USDT",
    "network": "POL",
    "tx": {
      "to": "0xcontract...",
      "data": "0xa9059cbb...",
      "value": "0",
      "chainId": 137
    },
    "approveTx": {
      "to": "0xtoken-contract...",
      "data": "0x095ea7b3...",
      "chainId": 137
    },
    "fees": {
      "applicationFee": 0.1,
      "protocolFee": 0.05,
      "bridgeFee": null
    }
  },
  "meta": {
    "message": "Transaction initialized successfully"
  }
}
```

#### b. Frontend Signing & Submission (Wagmi + Viem)

```javascript
import { useAccount, useWalletClient } from 'wagmi'
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const { data: walletClient } = useWalletClient()
const { address } = useAccount()

// Handle ERC20 approval if needed
if (response.data.approveTx) {
  const approveTx = {
    to: response.data.approveTx.to,
    data: response.data.approveTx.data,
    value: BigInt(0),
    chainId: response.data.approveTx.chainId
  }
  
  // Send approval transaction first
  const approveHash = await walletClient.sendTransaction({ ...approveTx, account: address })
  await publicClient.waitForTransactionReceipt({ hash: approveHash })
}

// Main transaction from /transactions response
const tx = {
  to: response.data.tx.to,
  data: response.data.tx.data,
  value: BigInt(response.data.tx.value || "0"),
  chainId: response.data.tx.chainId
}

const publicClient = createPublicClient({
  chain: mainnet,
  transport: http()
})

// Send signed transaction
const hash = await walletClient.sendTransaction({ ...tx, account: address })

// Optional: wait for confirmation
await publicClient.waitForTransactionReceipt({ hash })
```

✅ You can also use ethers.js or web3.js — just pass the exact `to`, `data`, `value`, and `chainId` from the response.

### Step 5: Get Transaction Activity

```bash
curl -X GET "https://api.reveel.id/v1/transactions/users/user-id/activities?page=1&pageSize=10" \
  -H "Authorization: Bearer your-api-key" \
  -H "Accept: application/json"
```

Response:

```json
{
  "success": true,
  "data": {
    "activities": [
      {
        "id": "activity-id",
        "txHash": "0xtxhash...",
        "amount": 1.5,
        "type": "SEND",
        "status": "COMPLETED",
        "token": "ETH",
        "network": "ETH",
        "createdAt": "2023-07-15T14:22:45.000Z",
        "updatedAt": "2023-07-15T14:23:12.000Z"
      }
    ],
    "pagination": {
      "totalCount": 1,
      "totalPages": 1,
      "currentPage": 1,
      "pageSize": 10
    }
  }
}
```

✅ Returns transaction history including amounts, routes, tokens, and fees.


---

# 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.reveel.id/getting-started/quickstart.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.