Register an identifier

A controller registers a typed value together with at least one payment destination. Registration is a management operation, not a resolver operation.

Before you call the API

1. Complete Business approval or use an approved wallet with Merchant Setup.
2. Call GET /v1/identifier-types and choose an active, registration-eligible type.
3. Check availability for the exact typed value.
4. Validate each chain, asset, contract, and address combination.

Authentication headers

Authorization: Bearer <approved-provider-key>
X-Controller-Wallet: 0xController…
X-Controller-Authorization: <signed authorization payload>
Idempotency-Key: unique-register-operation

Check availability

GET /v1/identifiers/email/pay%40example.com/availability

{ "available": true, "type": "email" }

Register

POST /v1/identifiers
{
  "type": "email",
  "value": "pay@example.com",
  "payment_options": [
    {
      "chain": "base",
      "asset": "USDC",
      "address": "0xRecipient…",
      "token_contract": "0xBaseUsdc…",
      "network_identifier": "eip155:8453"
    }
  ]
}

A successful response is 201 and normally starts in pending. The configured safety period must elapse before the identifier becomes payable.

{
  "id": "identifier_123",
  "type": "email",
  "value": "pay@example.com",
  "status": "pending",
  "controller": "controller_123",
  "registered_at": "2026-08-30T00:00:00.000Z",
  "activated_at": null,
  "payment_options": [{ "chain": "base", "asset": "USDC", "address": "0x…" }]
}