API Reference

Complete REST API and TypeScript SDK reference

Authentication

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

Authorization Headerhttp

Authorization: Bearer your_api_key_here

Generate API keys at /developers

Base URL

All API endpoints are available at the following base URL:

Production Base URLurl

https://api.zkira.xyz

REST Endpoints

POST/api/payments/create

Create a confidential payment escrow. Generates a claim URL for the recipient.

Request Bodyjson

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

Responsejson

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

Retrieve payment details by payment ID.

Responsejson

{
  "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 the on-chain status of a payment escrow.

Request Bodyjson

{
  "escrowAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
}

Responsejson

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

GET/api/escrows/:address

Get escrow details by on-chain address.

Responsejson

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

GET/api/escrows/creator/:pubkey

List all escrows created by a specific wallet address.

Responsejson

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

GET/api/health

Health check endpoint. No authentication required.

Responsejson

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

SDK Reference

ZkiraClient Class

Constructor

new ZkiraClient(connection: Connection, wallet: WalletAdapter)

Methods

createPaymentLink(params: CreatePaymentLinkParams): Promise<CreatePaymentLinkResult>

Create a confidential payment escrow with claim URL

claimPayment(params: ClaimPaymentParams): Promise<ClaimPaymentResult>

Claim a payment from escrow to recipient wallet

refundPayment(params: RefundPaymentParams): Promise<RefundPaymentResult>

Refund an unclaimed payment back to creator

registerMetaAddress(params: RegisterMetaAddressParams): Promise<RegisterMetaAddressResult>

scanForPayments(params: ScanForPaymentsParams): Promise<MatchedAnnouncement[]>

Scan blockchain for payments to registered meta-addresses

useZkiraPay React Hook

Configuration

{ payAppUrl?: string, apiUrl?: string, apiKey?: string }

Returns

{ createPayment, checkPaymentStatus, getPayment, status, error, lastResult, reset }

Webhooks

Configure webhooks to receive real-time notifications about payment events.

Event Types

• payment.completed - Payment claimed by recipient
• payment.expired - Payment expired without claim
• escrow.claimed - Escrow successfully claimed

Webhook Payload

Webhook Payloadjson

{
  "event": "payment.completed",
  "timestamp": 1704715800000,
  "data": {
    "paymentId": "pay_1234567890",
    "escrowAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "amount": 100000000,
    "tokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "recipient": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
  },
  "signature": "webhook_signature_here"
}

Webhook Handler Examplejavascript

// Webhook handler example
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-zkira-signature'];
  const payload = JSON.stringify(req.body);
  
  // Verify webhook signature
  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
    
  if (signature === expectedSignature) {
    // Handle webhook event
    console.log('Event:', req.body.event);
    console.log('Data:', req.body.data);
    res.status(200).send('OK');
  } else {
    res.status(401).send('Invalid signature');
  }
});

Error Responses

All errors follow a consistent format with appropriate HTTP status codes.

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

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED"
}

500 Internal Server Error

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

Rate Limiting

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

Rate Limit Headers

• X-RateLimit-Limit - Maximum requests per hour
• X-RateLimit-Remaining - Remaining requests in current window
• X-RateLimit-Reset - Unix timestamp when limit resets

Rate Limit Headers Examplehttp

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704719400