> 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/getting-started/quickstart.md).

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