Wallet API reference

The resolver is the only operation needed for a read-only wallet integration: send one typed identifier and consume a structured resolution response.

POST /v1/resolve

POST /v1/resolve
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "type": "custom",
  "value": "rezva-test-merchant"
}

type is an active, resolution-eligible identifier type. It may be omitted when the value is a full EMV / Bangla QR payload - the resolver classifies that as bangla_qr. value is normalized by the resolver according to that type. Every identifier value is capped at 700 characters.

POST /v1/resolve
{
  "type": "bangla_qr",
  "value": "00020101021126…6304B3C2"
}

For bangla_qr, paste the full QR text and resolve that exact string. Do not rewrite it into a merchant ID or chain address before calling the resolver.

Response

{
  "protocol_version": "1",
  "status": "active",
  "payment_ready": true,
  "identifier": {
    "type": "email",
    "value": "pay@example.com",
    "normalized_value": "pay@example.com"
  },
  "registration": {
    "registered_at": "2026-08-29T12:00:00.000Z",
    "activated_at": "2026-08-29T13:00:00.000Z",
    "last_updated": "2026-08-29T12:00:00.000Z",
    "last_payment_update": null
  },
  "payment_options": [
    {
      "chain": "base",
      "asset": "USDC",
      "address": "0x…",
      "token_contract": "0x…",
      "network_identifier": "eip155:8453",
      "payment_ready": true
    }
  ]
}

Payment decision

const canPay =
  result.status === "active" &&
  result.payment_ready === true &&
  result.payment_options.some((option) => option.payment_ready === true);

• status is the registry lifecycle state.
• payment_ready is the top-level payability signal.
• payment_options contains chain, asset, address, token contract, and constraints.
• registration timestamps support trust and warning UX.
• trust.warnings, when present, must be shown before confirmation.

Discovery and error handling

• GET /v1/identifier-types - discover active types and capabilities.
• GET /health - check service health; it does not authenticate.
• 401 - authentication or provider approval failure.
• 400 - invalid identifier or unsupported type.
• 403 RESOLVE_POLICY_DENIED - provider resolve policy blocked this value or module.
• 404 - no payment destination found for the normalized identifier.
• 429 - retry after the response’s Retry-After value.

Optional provider resolve policy

By default a provider key can resolve everything. Operators may attach an optional resolve_policy to a provider so the API enforces module and blocklist rules. Omit the policy (or leave fields unset) to keep open behavior.

{
  "unr": true,
  "registry": true,
  "allow_namespaces": [".eth", ".base"],
  "deny_namespaces": [".sol"],
  "deny_types": ["phone"],
  "blocklist": ["spam.eth", "blocked@example.com"]
}

• unr: false - disable Universal Name Resolution.
• registry: false - disable Rezva registry identifiers (email, QR, namespaces, …).
• allow_namespaces / deny_namespaces - filter external TLDs when UNR is on.
• deny_types - block registry types even if listed in allowed_identifier_types.
• blocklist - reject exact identifier values (case-insensitive).

Wallets can mirror the same rules client-side with shouldAcceptPaste before calling resolve. See SDKs and integration recipes.

See the OpenAPI specification for the machine-readable contract. Free API keys cannot call registry mutation endpoints.