Settlex Flow - Gateway

The Settlex Gateway is a pay-per-request proxy that lets you call third-party provider APIs using your credits.

Base URL: settlex-gateway.luganodes.com Protocol: HTTP/REST Authentication: API Key

Prerequisites

Before using the gateway you must have a funded Settlex account. Set up is done through the Settlex API (/api service):

Step	API Call	What You Get
1. Create an account	POST /api/onboarding/signup	User account
2. Log in	POST /api/onboarding/login	JWT token
3. Create a Canton party	POST /api/party/create (Auth: Bearer token)	Ledger identity (partyId)
4. Generate an API key	POST /api/api-key/create (Auth: Bearer token)	Raw API key (shown once)
5. Fund your party	Transfer Canton Coin to your party via the Canton Network	Spendable balance

Once you have an active API key and a funded balance, you are ready to use the gateway.

Authentication

Every gateway request must include your API key in the x-settlex-api-key header.

x-settlex-api-key: <your_api_key>

The gateway verifies it against the database, and resolves your Canton party identity. The key header is stripped before the request is forwarded to the upstream provider — providers never see your Settlex credentials.

Authentication Errors

Status	Body	Condition
401	{ "message": "Unauthorized" }	Missing header or unknown API key
403	{ "message": "API Key is no longer active" }	Key has been deactivated
403	{ "message": "User does not have a party" }	User has no Canton party onboarded with us

Making Requests

All requests follow one pattern:

<METHOD> /gateway/<providerKey>/<upstream_path>

Component	Description
<METHOD>	Any HTTP method (GET, POST, PUT, DELETE, etc.)
<providerKey>	The unique identifier of the registered provider
<upstream_path>	The path the provider expects (forwarded as-is)

The gateway strips /gateway/<providerKey> from the path before forwarding. For example:

POST /gateway/acme-ai/v1/chat/completions

is forwarded to the acme-ai provider as:

POST /v1/chat/completions

The request body, query parameters, and most headers are forwarded transparently. The provider's response (status code, headers, body) is returned to you as-is.

Example

curl -X POST https://settlex-gateway.luganodes.com/gateway/acme-ai/v1/chat/completions \
  -H "x-settlex-api-key: your_api_key_here" \
  -H "idempotency-key: unique-request-id-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

Required Headers

Every gateway request must include both of these headers:

Header	Type	Description
x-settlex-api-key	string	Your Settlex API key
idempotency-key	string	A unique key for this request (see Idempotency)

Any additional headers your provider expects (e.g. Content-Type) should be included as normal.

Request Lifecycle

Every request passes through four stages before the provider response reaches you:

Client Request
  → 1. Authentication     Verify API key, resolve party
  → 2. Idempotency        Check for duplicate request
  → 3. Reservation         Reserve CC balance for this request
  → 4. Proxy               Forward to provider, return response

1

Authentication

Your API key is validated and your Canton party ID is resolved.

2

Idempotency

The idempotency-key is checked against existing reservations for the same provider. If a duplicate is found, the request is rejected with 409.

3

Reservation

The provider's cost (in USD) is converted to Canton Coin at the current exchange rate. That amount is reserved from your available balance. A reservation record is created.

4

Proxy

The request is forwarded to the provider. On a successful upstream response (2xx/3xx), the reservation is marked registered. On failure, the reservation is marked failed and reserved funds are released back to your balance.

Error Responses

Provider Errors

If the upstream provider successfully sends a full HTTP response (success or error), they are forwarded to you as-is. If the gateway encounters errors while communicating (internal or transport level error) with the provider for any reason, custom errors are sent by the gateway.

Gateway Errors

All gateway errors return JSON in the format:

{
  "message": "Human-readable error description"
}

Status	Message	Stage	Cause
400	"Idempotency key is required"	Idempotency	Missing idempotency-key header
400	"Idempotency key must be a string, and not an array"	Idempotency	Header has multiple values
400	"Provider key is required"	Reservation	Invalid URL path
401	"Unauthorized"	Auth	Missing or invalid API key
403	"API Key is no longer active"	Auth	Deactivated API key
403	"User does not have a party"	Auth	No Canton party on account
403	"Party does not have enough balance"	Reservation	Insufficient CC balance
403	"Provider is not active"	Reservation	Provider is disabled or degraded
404	"Provider not found"	Reservation / Proxy	Unknown providerKey
409	"Idempotency key already exists"	Idempotency / Reservation	Duplicate request (see Idempotency)
500	"Internal server error"	Any	Unexpected server error
502	"Bad gateway: provider unavailable"	Proxy	Provider connection failed
502	"Bad gateway: upstream aborted response"	Proxy	Provider dropped the connection
502	"Bad gateway: upstream response stream error"	Proxy	Provider response stream broke

On any upstream failure (4xx, 5xx, timeout, connection error), reserved funds are automatically released.

Idempotency

Every request requires an idempotency-key header — a client-generated string that uniquely identifies the request. Idempotency keys are scoped to the combination of:

• idempotency key (your value)

• provider key (from the URL path)

• party ID (from your account)

This means the same idempotency key can be safely reused across different providers.

Duplicate Request Response

If a reservation already exists for the same (idempotencyKey, providerKey, partyId) tuple, the gateway returns:

{
  "message": "Idempotency key already exists",
  "reservation": {
    "idempotencyKey": "unique-request-id-001",
    "partyId": "party-abc123::1220...",
    "providerKey": "acme-ai",
    "costInUSD": 0.03,
    "status": "registered",
    "createdAt": "2025-06-15T10:30:00.000Z",
    "updatedAt": "2025-06-15T10:30:01.000Z"
  }
}

Reservation Statuses

Status	Meaning
request_in_flight	Request sent to provider, awaiting response
registered	Provider responded successfully (2xx/3xx)
failed	Provider returned an error or was unreachable; funds released
queued	Processing has begun, awaiting ledger finalization
settled	Transaction completed on ledger

Balance & Billing

Each provider has a fixed cost per request in USD. When you make a request, the gateway:

1. Converts the USD cost to Canton Coin (CC) using the current exchange rate.

2. Checks that your available balance minus reserved balance is sufficient.

3. Atomically reserves the CC amount from your balance.

On success, the reservation stays and the funds are considered spent. On failure, the reserved amount is released back to your available balance.

You can check your current balance at any time via the Settlex API:

curl -X GET https://settlex-api.luganodes.com/api/balance \
  -H "Authorization: Bearer <your_jwt_token>"

{
  "balance": 1000.50,
  "reservedBalance": 3.25
}

• balance — total available Canton Coin

• reservedBalance — amount currently locked for in-flight requests

• Spendable = balance - reservedBalance