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

API keys are provided manually upon approval via email request.

Please send your request from company email to: [email protected]

Prerequisites

Make sure you have:

• A valid API key

• A tool like curl, Postman, or any HTTP client

Step 1: Create a User

curl -X POST https://api.reveel.id/v1/users \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "twitterUsername": "alice123",
    "walletAddress": "0x123abc456def789ghi"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "user-id",
    "email": "[email protected]",
    "walletAddress": "0x123abc456def789ghi",
    "twitterUsername": "alice123",
    "createdAt": "2023-07-15T12:30:45.000Z"
  },
  "meta": {
    "message": "User created successfully"
  }
}

Step 2: Claim a PayID

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:

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

For premium PayIDs:

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

Step 3: Create a Route

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:

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

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:

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

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

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

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:

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