Find an event and activate a wallet

This is the flow that answers "I'm an already-registered user, I want to join an event — how does the app find that event and create my wallet in it?"

1. Participant types the event code (e.g. AXY-9898)
   or scans a QR carrying the same code
        ↓
2. GET /v1/wallet/events/by-code/AXY-9898   (wallet-control-api, via the Edge)
        ↓
   returns an event preview — creates NOTHING yet
        ↓
3. App shows the event's name/date/currency, participant confirms
        ↓
4. PUT /v1/events/{eventId}/wallets/current   (regional wallet-api, via the Edge)
        ↓
   creates (or returns, if it already existed) the participant's wallet for that event

Steps 1–2: look up the event by code

curl

curl http://127.0.0.1:8787/v1/wallet/events/by-code/AXY-9898 \
  -H "Authorization: Bearer <participant accessToken>"

JavaScript

const response = await fetch(
  "http://127.0.0.1:8787/v1/wallet/events/by-code/AXY-9898",
  { headers: { Authorization: `Bearer ${accessToken}` } },
);
const event = await response.json();

Python

import requests

response = requests.get(
    "http://127.0.0.1:8787/v1/wallet/events/by-code/AXY-9898",
    headers={"Authorization": f"Bearer {access_token}"},
)
event = response.json()

Response

{
  "eventId": "018f26d7-8a7b-7e7d-8c96-4f0b8d0f2b10",
  "name": "Summer Festival",
  "slug": "summer-festival",
  "eventCode": "AXY-9898",
  "timezone": "America/Sao_Paulo",
  "currencyCode": "BRL",
  "startsAt": "2026-12-15T18:00:00.000Z",
  "endsAt": "2026-12-16T04:00:00.000Z"
}

Important details:

• The code is accepted with or without the dash, case-insensitively — axy9898, AXY-9898, and Axy 9898 all resolve the same way.
• This endpoint requires login (a participant token) — there's no public version. That limits how many code guesses anyone can attempt.
• Only an event with status=active is found. An event still provisioning, suspended, or archived returns 404 EVENT_NOT_FOUND — the same generic response as "code doesn't exist", on purpose.
• This call creates no wallet at all. It's preview only, so the app can show it before confirming.

Step 4: activate the wallet

curl

curl -X PUT http://127.0.0.1:8787/v1/events/018f26d7-8a7b-7e7d-8c96-4f0b8d0f2b10/wallets/current \
  -H "Authorization: Bearer <participant accessToken>"

JavaScript

const response = await fetch(
  `http://127.0.0.1:8787/v1/events/${eventId}/wallets/current`,
  { method: "PUT", headers: { Authorization: `Bearer ${accessToken}` } },
);
const wallet = await response.json();

Python

import requests

response = requests.put(
    f"http://127.0.0.1:8787/v1/events/{event_id}/wallets/current",
    headers={"Authorization": f"Bearer {access_token}"},
)
wallet = response.json()

Response

{
  "walletId": "0728a...",
  "eventId": "018f26d7-8a7b-7e7d-8c96-4f0b8d0f2b10",
  "status": "active",
  "availableAmountMinor": 0,
  "heldAmountMinor": 0
}

• Idempotent: calling it again with the same participant/event returns the same wallet, without duplicating or resetting the balance.
• userId comes from the JWT — the client never picks whose wallet it is.
• Runs in a single regional transaction: it creates the wallet, the zeroed balance, and the ledger accounts (WALLET_AVAILABLE, WALLET_HELD) together. If any part fails, nothing is written.
• Once created, the wallet is synced to the global directory asynchronously (seconds, not instantaneous) — see My wallets and Architecture → overview to understand that delay.

Checking the wallet afterward

GET /v1/events/{eventId}/wallets/current
Authorization: Bearer <participant accessToken>

Same response shape as the PUT. Returns 404 if the participant hasn't activated a wallet for that event yet — in that case, call the PUT first.