Core API

Resolve API

Resolution is the heart of Settla. It turns an alias into an identity plus the endpoints the calling consumer is authorized to see — filtered by privacy level, scope, and consent. It is read-only and moves no money.

POST/v1/resolve

Requires scope resolve (or *). Provide either a single alias string, or an explicit type + value pair.

Request body

Field	Type	Description
`alias`optional	`string`	The identifier to resolve, e.g. `@john`, `+2348012345678`, `jo@x.com`. Settla detects and normalizes the type. Provide this or `type` + `value`.
`type`optional	`string`	Explicit alias type: `username`, `phone`, `email`, `merchant_handle`, `payment_link`. Use with `value`.
`value`optional	`string`	The raw value when using the explicit `type` form, e.g. `john`.

Example request

curl https://api.settla.network/v1/resolve \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"alias":"@john"}'

# explicit type form
curl https://api.settla.network/v1/resolve \
  -H "Authorization: Bearer sk_test_..." \
  -d '{"type":"username","value":"john"}'

Response

{
  "identity": "idn_2x9...",
  "type": "user",
  "matched_alias": { "type": "username", "value": "john" },
  "endpoints": [
    { "id": "end_a1...", "type": "crypto_wallet", "address": "0x1234…abcd",
      "capabilities": [ { "asset": "USDC", "network": "polygon", "rail": "onchain" } ] },
    { "id": "end_b2...", "type": "bank_account", "last4": "6789", "token": null,
      "capabilities": [ { "asset": "USD", "rail": "ach" } ] }
  ],
  "disclosure": { "consumer": "apc_...", "total_endpoints": 3, "disclosed": 2 },
  "livemode": false,
  "request_id": "req_7k2..."
}

Field	Description
identity	Public identity ID (idn_…) that owns the alias.
type	Identity type: user, merchant, business, …
matched_alias	The normalized alias type and value that matched.
endpoints[]	Disclosed endpoints only. Each has id, type, capabilities, and a per-type address projection (see below).
disclosure	consumer (apc_…), total_endpoints owned, and how many were disclosed to you.
livemode	false for test keys, true for live keys.
request_id	req_… — also returned as the Settla-Request-Id header.

Privacy-aware disclosure

Resolution never returns more than you are entitled to see. Each endpoint passes a fail-closed filter before it is included:

Environment match — a test key cannot see live data and vice versa.
Scope — your key must carry resolve or *, else 403.
Alias privacy gate — public and unlisted resolve on exact match; private returns a uniform 404; consent_required needs an active grant.
Identity status — only active identities resolve.
Per-endpoint privacy + consent — each endpoint is included only if active and allowed by its privacy level (and a valid ConsentGrant for consent_required).

Minimal disclosure

The response never reveals the existence of endpoints you cannot see — not-found and not-permitted are indistinguishable in both shape and timing. disclosure.total_endpoints counts what the identity owns, but no detail of the hidden ones is exposed. See Privacy & Security.

Per-type address projection

Endpoint type	What is returned
crypto_wallet	Full public receive address (decrypted) + capabilities.
bank_account, exchange_account, payment_processor_account, merchant_account	last4 + an optional token only — never the full number.
internal_settla_endpoint, future_endpoint	public_id + type only.

Bulk resolution

POST/v1/resolve/bulk

Resolve up to 100 identifiers in one request. Each item carries its own status, so a single bad item never fails the batch.

curl https://api.settla.network/v1/resolve/bulk \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"items":["@john","+2348012345678",{"type":"email","value":"jo@x.com"}]}'

{
  "results": [
    { "alias": "@john", "status": "resolved", "identity": "idn_...", "endpoints": [ ... ] },
    { "alias": "+2348012345678", "status": "consent_pending" },
    { "alias": "jo@x.com", "status": "error",
      "error": { "type": "not_found_error", "code": "alias_not_found" } }
  ]
}

Per-item status is one of resolved, consent_pending, or error.

Errors

Status	Code	When
400	invalid_request	Missing alias / type+value, or an unparseable identifier.
401	authentication_error	Missing, malformed, or revoked key.
403	permission_error	Key lacks the resolve scope.
404	alias_not_found	No resolvable identity (also returned for private / no-consent — uniform).
429	rate_limited / scraping_quota_exceeded	Velocity or distinct-alias breadth limit hit.

All errors use the canonical envelope — see Errors.