API Documentation

Complete reference for the ZKIRA Pay payment API

Authentication

All API requests require authentication using your API key in the Authorization header:

Authorization: Bearer your_api_key_here

Base URL

https://api.zkira.xyz

POST/api/payments/create

Create a confidential payment

Request Body

{
  "amount": 100,
  "tokenMint": "USDC",
  "expiryDays": 7
}

Response

{
  "paymentId": "pay_1234567890",
  "claimUrl": "https://app.zkira.xyz/claim/abc123",
  "payUrl": "https://app.zkira.xyz/pay/xyz789",
  "amount": 100,
  "tokenMint": "USDC",
  "claimHash": "hash_abc123",
  "metaAddress": "meta_xyz789",
  "expiresAt": "2024-01-15T10:30:00Z"
}

GET/api/payments/:id

Get payment by ID

Response

{
  "payment": {
    "paymentId": "pay_1234567890",
    "amount": 100,
    "tokenMint": "USDC",
    "claimHash": "hash_abc123",
    "metaAddress": "meta_xyz789",
    "expiresAt": "2024-01-15T10:30:00Z",
    "createdAt": "2024-01-08T10:30:00Z"
  }
}

POST/api/payments/status

Check escrow status

Request Body

{
  "escrowAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
}

Response

{
  "escrow": {
    "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "creator": "4uQeVj5tqViQh7yWWGStvkEG1Zmhx6uasJtWCJziofM",
    "tokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "amount": 100000000,
    "claimed": false,
    "refunded": false,
    "expiry": 1705320600,
    "createdAt": 1704715800
  }
}

GET/api/escrows/:address

Get escrow by address

Response

{
  "escrow": {
    "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "creator": "4uQeVj5tqViQh7yWWGStvkEG1Zmhx6uasJtWCJziofM",
    "tokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "amount": 100000000,
    "claimed": false,
    "refunded": false,
    "expiry": 1705320600
  }
}

GET/api/escrows/creator/:pubkey

List escrows by creator

Response

{
  "escrows": [
    {
      "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      "creator": "4uQeVj5tqViQh7yWWGStvkEG1Zmhx6uasJtWCJziofM",
      "amount": 100000000,
      "claimed": false,
      "tokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    }
  ],
  "count": 1
}

GET/api/health

Health check

Response

{
  "status": "ok",
  "timestamp": 1704715800000,
  "version": "1.0.0"
}

Error Responses

The API uses conventional HTTP response codes to indicate success or failure:

400 - Bad Request

{
  "error": "Invalid request parameters",
  "code": "INVALID_PARAMS"
}

401 - Unauthorized

{
  "error": "Invalid or missing API key",
  "code": "UNAUTHORIZED"
}

404 - Not Found

{
  "error": "Resource not found",
  "code": "NOT_FOUND"
}

500 - Internal Server Error

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR"
}

Rate Limiting

The API is rate limited to 1000 requests per hour per API key. Rate limit information is included in response headers:

X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1609459200