API Reference

Complete reference for the WalletGate REST API.

Base URL

https://api.walletgate.app

Authentication

All API requests require an API key in the Authorization header:

Authorization: Bearer wg_test_your_api_key_here

Getting an API Key

• New? Create an account to get a test key (wg_test_*, free 100/month)
• Existing user? Log in to view your keys
• Live keys (wg_live_*) are available on paid plans (Starter+)

API Key Format

wg_<environment>_<publicId>.<secret>

Examples:

• Test: wg_test_abc123xyz.def456uvw
• Live: wg_live_xyz789abc.uvw012def

Learn about Test vs Live →

Endpoints

Create Verification Session

POST /v1/verify/sessions

Create a new verification session for a user to complete.

Request:

{
  "checks": [
    { "type": "age_over", "value": 18 },
    { "type": "residency_eu" },
    { "type": "identity_verified" }
  ],
  "redirectUrl": "https://your-app.com/success",
  "webhookUrl": "https://your-app.com/webhook",
  "metadata": {
    "userId": "user_123",
    "orderId": "order_456"
  },
  "enableAI": true
}

Response (201 Created):

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "environment": "test",
    "testMode": true,
    "verificationUrl": "openid4vp://verify?request_uri=https://...",
    "qrCode": "data:image/png;base64,...",
    "expiresAt": "2024-12-31T23:59:59Z",
    "createdAt": "2024-12-31T12:00:00Z"
  }
}

View detailed endpoint docs →

---

Get Verification Session

GET /v1/verify/sessions/{sessionId}

Retrieve the status and results of a verification session.

Parameters:

• sessionId (path, required): The UUID of the session

Response (200 OK):

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "environment": "test",
    "results": {
      "age_over_18": true,
      "residency_eu": true,
      "identity_verified": true
    },
    "riskScore": 0.05,
    "aiInsights": [
      "Low risk transaction",
      "Identity confidence: 99.5%"
    ],
    "metadata": {
      "userId": "user_123"
    },
    "completedAt": "2024-12-31T12:05:30Z",
    "createdAt": "2024-12-31T12:00:00Z"
  }
}

View detailed endpoint docs →

---

Health Check

GET /health

Check API health status (no authentication required).

Response (200 OK):

{
  "status": "ok",
  "timestamp": "2024-12-31T12:00:00Z",
  "version": "1.0.0"
}

Check Types

Age Verification

Verify that a user is over a specific age.

{ "type": "age_over", "value": 18 }

Supported values: 13, 16, 18, 21, or any custom age

Result field: age_over_<value> (e.g., age_over_18)

Residency Verification

Verify that a user is a resident of an EU member state.

{ "type": "residency_eu" }

Result field: residency_eu

Identity Verification

Verify that the user's identity has been confirmed.

{ "type": "identity_verified" }

Result field: identity_verified

Verification Status

Status	Description
pending	Session created, awaiting user action
in_progress	User is currently verifying
completed	Verification successfully completed
failed	Verification failed
expired	Session expired (15 minutes timeout)
cancelled	User cancelled verification

Response Codes

Code	Description
200	Success
201	Resource created
400	Bad request (validation error)
401	Unauthorized (invalid API key)
403	Forbidden (quota exceeded)
404	Resource not found
429	Too many requests (rate limited)
500	Internal server error

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid check type",
    "field": "checks[0].type",
    "details": {
      "allowed": ["age_over", "residency_eu", "identity_verified"]
    }
  }
}

View all error codes →

Rate Limits

Rate limits are based on your plan:

Plan	Requests/Second	Requests/Month
Free Trial	No limit	100 (test only)
Starter	10/s	1,000
Growth	50/s	10,000
Scale	200/s	50,000
Enterprise	Custom	Custom

Rate limit headers are included in all responses:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1609459200

Webhooks

Receive real-time notifications when verification events occur.

Learn about webhooks →

Interactive API Explorer

Try the API directly in your browser with our interactive Swagger UI:

Open API Explorer →

SDK Integration

For easier integration, use our TypeScript SDK:

import { WalletGate } from '@walletgate/eudi';

const client = new WalletGate({
  apiKey: process.env.WALLETGATE_API_KEY,
});

View SDK documentation →

Need Help?

• 📧 Email: [email protected]
• 📖 Check the FAQ
• 💬 Book a demo