@walletgate/eudi

EU Digital Identity Wallet verification made simple.

WalletGate is a Verifier/Relying Party SDK for the EU Digital Identity Wallet ecosystem. It lets you create verification sessions, direct users to their wallet, and fetch signed results using real EU trust infrastructure.

How it works

Simple verification flow with a smooth user journey.

+-------------------------+       +----------------------+       +----------------------+
|  1. Show QR             |       |  2. User approves    |       |  3. Verified          |
|                         |       |                      |       |                      |
|  your-app.com/checkout  |  -->  |  Age Verification    |  -->  |      Verified        |
|                         |       |  your-app.com        |       |  Age 18+ confirmed   |
|  [QR Code]              |       |  Age over 18  [x]    |       |                      |
|  Scan with EUDI Wallet  |       |  [Approve]           |       |      [Done]          |
+-------------------------+       +----------------------+       +----------------------+

1. Show QR -- Your app creates a verification session and displays a QR code
2. User approves -- The user scans with their EUDI Wallet and approves the data request
3. Verified -- Your app receives the cryptographically signed result

Installation

::: code-group

npm install @walletgate/eudi

pnpm add @walletgate/eudi

yarn add @walletgate/eudi

:::

Optional CLI (no install):

npx @walletgate/eudi walletgate help
# Prints: Get a free test API key + Docs links

Quick Start

WalletGate supports two environments:

• Test keys: wg_test_*
• Live keys: wg_live_*

1. Initialize

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

const eudi = new WalletGate({
  apiKey: process.env.WALLETGATE_API_KEY,
  baseUrl: 'https://api.walletgate.app'
});

2. Start Verification

Option A: Hosted Page (recommended) — We handle the UI.

const session = await eudi.startVerification({
  checks: [
    { type: 'age_over', value: 18 },
    { type: 'residency_eu' }
  ],
  successUrl: 'https://yourapp.com/verified',
  cancelUrl: 'https://yourapp.com/checkout'
});

// Redirect user to WalletGate's hosted verification page
window.location.href = session.hostedUrl;

The hosted page handles QR codes, wallet deep-linking, and real-time status updates. The user is redirected back to your successUrl or cancelUrl with a signed JWT token.

Option B: Custom UI — Render your own QR code.

const session = await eudi.startVerification({
  checks: [
    { type: 'age_over', value: 18 },
    { type: 'residency_eu' }
  ]
});

// Show the verification URL as a QR code in your own UI
window.location.href = session.verificationUrl;

3. Get Results

const result = await eudi.getResult(session.id);

if (result.status === 'completed') {
  console.log('Age over 18:', result.results?.age_over_18);
  console.log('EU resident:', result.results?.residency_eu);
}

Test Wallet Simulator

In test mode (wg_test_* keys), the hosted page includes a "Use Test Wallet" button. This opens a browser-based simulator that lets you approve or reject verification without a real EUDI Wallet — perfect for end-to-end testing during development.

QR Code Helper (Optional)

If you want to show a QR code for cross-device flows, install the optional qrcode dependency:

npm install qrcode

Then generate a data URL locally (no external services):

import { makeQrDataUrl } from '@walletgate/eudi';
const qrCode = await makeQrDataUrl(session.verificationUrl);

Webhook Verification (Node)

import * as crypto from 'crypto';

// Required for verifyWebhook in Node environments
(globalThis as any).__WG_NODE_CRYPTO = crypto;

app.post('/webhooks/walletgate', (req, res) => {
  const signature = req.headers['wg-signature'];
  const timestamp = req.headers['wg-timestamp'];

  const isValid = eudi.verifyWebhook(
    req.rawBody,
    signature,
    process.env.WEBHOOK_SECRET,
    timestamp
  );

  if (!isValid) return res.status(400).send('Invalid signature');
  res.sendStatus(200);
});

REST API (Other Languages)

Use the REST API directly in any language:

::: code-group

curl -X POST https://api.walletgate.app/v1/verify/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"checks":[{"type":"age_over","value":18}]}'

import requests, os

response = requests.post(
    'https://api.walletgate.app/v1/verify/sessions',
    headers={'Authorization': f'Bearer {os.getenv("WALLETGATE_API_KEY")}'},
    json={'checks': [{'type': 'age_over', 'value': 18}]}
)
print(response.json())

:::

API Reference (Short)

• new WalletGate(config)
• startVerification(input)
• getResult(sessionId)
• verifyWebhook(rawBody, signature, secret, timestamp)
• makeQrDataUrl(url)

See the docs for full reference, error handling, and examples.

Links

• Docs: https://docs.walletgate.app/
• Get early access: https://walletgate.app
• Discord: https://discord.gg/KZ8sP5Ua
• Support: [email protected]
• Security: [email protected]
• Repo: https://github.com/walletgate/eudi-sdk

License

Apache-2.0 - See LICENSE.