Core API

Identities, Aliases & Endpoints

The registry is the write side of Settla. An identity is permanent; aliases are how humans address it; endpoints are where value can land. Privacy is set per alias and per endpoint, independently.

These three records map directly to the three principles: identity is permanent, endpoints are replaceable, routes are dynamic. You own and mutate identities/aliases/endpoints through the control plane; the resolver only reads them.

Identities

POST/v1/identities

An identity is a permanent record (idn_…) with a type and a status. Its UUID is never freed. Scope: identities:write.

Field	Type	Description
`type`required	`string`	`user`, `merchant`, `business`, `organization`, or `machine`.
`display_name`optional	`string`	Human-readable label shown in dashboards and trust.
`default_privacy_level`optional	`string`	Default for new aliases/endpoints. Defaults to `unlisted`.

curl https://api.settla.network/v1/identities \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user",
    "display_name": "John Rivera",
    "default_privacy_level": "unlisted"
  }'
# => { "id": "idn_2x9...", "type": "user", "status": "active", ... }

Other identity operations:

GET/v1/identities/:id

GET/v1/identities

PATCH/v1/identities/:id

PATCH updates status, display_name, or default_privacy_level; GET /v1/identities is cursor-paginated.

Aliases

POST/v1/aliases

An alias (als_…) is a human-friendly identifier pointing to an identity. On create, Settla normalizes the value (lowercasing, stripping the @, E.164 for phones, confusable-folding), rejects reserved words, and returns 409 conflict_error on a duplicate. Scope: aliases:write.

curl https://api.settla.network/v1/aliases \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "identity": "idn_2x9...",
    "type": "username",
    "value": "@John",
    "privacy_level": "unlisted",
    "is_primary": true
  }'
# value is normalized: "@John" -> username "john"

Supported alias types:

Type	Example
username	@john
phone	+2348012345678 (E.164)
email	jo@x.com
merchant_handle	@acme
payment_link	settla.link/acme
qr	QR-derived identifier

Manage aliases:

GET/v1/identities/:id/aliases

PATCH/v1/aliases/:id

DELETE/v1/aliases/:id

PATCH changes privacy_level or is_primary; DELETE releases the alias and sets a cooldown before it can be re-registered (squatting defense).

Endpoints

POST/v1/endpoints

An endpoint (end_…) is a typed destination owned by an identity, carrying capabilities (asset/network/rail) and a privacy level. Sensitive address values are encrypted at rest (AES-256-GCM, bound to the endpoint), so the raw number is never stored in plaintext or logged. Scope: endpoints:write.

Field	Type	Description
`identity`required	`string`	The owning identity (idn_…).
`type`required	`string`	One of the endpoint types below.
`address`required	`string`	Raw destination (wallet address, account number, …). Encrypted at rest; disclosed per type.
`privacy_level`optional	`string`	`public` · `unlisted` · `private` · `consent_required`. Defaults to the identity default.
`priority`optional	`number`	Higher wins ties when routing; default ordering hint.
`capabilities`optional	`object[]`	Each: `asset`, `network`, `rail`, `supports_instant`, optional `min_amount`/`max_amount` (routing context only — never a charge).

curl https://api.settla.network/v1/endpoints \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "identity": "idn_2x9...",
    "type": "crypto_wallet",
    "address": "0x1234abcd...5678",
    "privacy_level": "public",
    "priority": 100,
    "capabilities": [
      { "asset": "USDC", "network": "polygon", "rail": "onchain", "supports_instant": true }
    ]
  }'

Endpoint types and how they are disclosed:

Type	Disclosure
crypto_wallet	On-chain receive address; full address disclosed.
bank_account	Bank account / IBAN; only last4 + token disclosed.
exchange_account	Exchange deposit reference; last4 + token only.
payment_processor_account	PSP account (e.g. processor ref); last4 + token only.
merchant_account	Merchant acquiring account; last4 + token only.
internal_settla_endpoint	Settla-internal addressing; public_id + type only.
future_endpoint	Reserved type; public_id + type only.

Manage endpoints:

GET/v1/identities/:id/endpoints

PATCH/v1/endpoints/:id

DELETE/v1/endpoints/:id

Privacy levels

Both aliases and endpoints carry a privacy level, set independently. The effective disclosure is the intersection: an unlisted alias can still expose only its public or consented endpoints. An unknown/null level is treated as private (fail-closed).

Level	Meaning
public	Resolvable by anyone with the exact identifier. Not enumerable/searchable (except opt-in public directory).
unlisted	Default. Resolvable only on exact match; never listed, searched, or fuzzy-matched.
private	Never disclosed externally. Owner/admin use only.
consent_required	Disclosed only under a valid ConsentGrant for that consumer ↔ identity.

Tip

Because endpoints are replaceable, a recipient can switch banks or wallets by adding a new endpoint and removing the old one — the alias keeps resolving and no payer needs to be told to “re-enter details.”