Getting started

Quickstart

Mint a test key, then resolve @john to its disclosed endpoints. The whole loop takes a single request — Settla never touches the money.

1. Get an API key

Create an organization, then mint a key for its default consumer. In a production setup you do this in the dashboard; in dev, the bootstrap endpoints let you do it over the API. Use a test key while you build — it only ever sees test-mode data.

# 1. Create an organization (also mints a default api_consumer)
curl https://api.settla.network/v1/organizations \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Payments"}'

# 2. Mint a test secret key for that consumer (returned ONCE)
curl https://api.settla.network/v1/api-consumers/apc_.../api-keys \
  -H "Content-Type: application/json" \
  -d '{"environment":"test","scopes":["resolve","recommend_route"]}'
# => { "secret": "sk_test_8f...c2", "prefix": "sk_test", "last4": "...c2" }

Heads up

The raw secret (sk_test_…) is shown exactly once. Store it in a secret manager; Settla only keeps a salted hash. See Authentication.

2. Install an SDK (optional)

You can call the REST API directly, or use an official SDK. Both read the key from the environment by default.

npm install @settla/sdk

3. Resolve an alias

Send the alias you want to resolve. Settla normalizes the identifier (@john → username john), finds the identity, and returns only the endpoints your key is authorized to see.

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

A successful response looks like this:

{
  "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..."
}

Notice disclosure.total_endpoints is 3 but disclosed is 2: a third endpoint exists but is gated by privacy or consent and is omitted. The response shape never reveals what you cannot see.

Test mode

Anything created with a test key (sk_test_… / pk_test_…) lives in an isolated environment, and livemode is false. Verification challenges in dev accept the magic code 000000.

Next steps

Recommend a route with POST /v1/recommend-route.
Register your own identities, aliases, and endpoints — see the registry guide.
Receive events with webhooks.

Endpoints used here

POST/v1/organizations

POST/v1/api-consumers/:id/api-keys

POST/v1/resolve