Settlex Flow - Onboarding

Settlex Flow is the real-time settlement layer for API consumption. Developers and AI agents route API calls through the Settlex gateway and pay based on usage — no subscriptions, no credit top-ups.

Version: 1.0.0 Base URL: settlex-api.luganodes.com Protocol: HTTP/REST

---

Authentication

All endpoints under Party, API Key, and Balance require a valid JWT token passed via the Authorization header using the Bearer scheme.

Authorization Header Format

Authorization: Bearer <jwt_token>

Authentication Failure Responses

Status Code	Response Body	Condition
401	{ "message": "Unauthorized" }	Missing or malformed Authorization header
401	{ "message": "Invalid token" }	Token is valid JWT but payload doesn't match schema
401	{ "message": "Unauthorized" }	User not found in database or token verification failed

---

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent JSON format:

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

Common Error Codes

Status Code	Meaning	Typical Cause
400	Bad Request	Request body validation failed (Zod schema errors)
401	Unauthorized	Missing, invalid, or expired JWT token
404	Not Found	Requested resource does not exist
409	Conflict	Resource already exists (duplicate email, party, etc.)
500	Internal Server Error	Unexpected server-side error or ledger failure
429	Rate Limit Exceeded	A default rate limit of 300 requests every 15 minutes

Validation Error Format

When request body validation fails, the error message contains field-level details joined by semicolons:

{
  "message": "email: Invalid email; password: String must contain at least 8 character(s)"
}

---

Endpoints

Health

GET /api/health

A simple health check endpoint to verify the API server is running and responsive.

Authentication: None

Request

No request body or query parameters required.

Response

200 OK

The server is healthy and operational.

{
  "message": "OK"
}

Field	Type	Description
message	string	Health status confirmation

Example

curl -X GET http://settlex.luganodes.com/api/health

{
  "message": "OK"
}

---

Onboarding

POST /api/onboarding/signup

Creates a new user account

Authentication: None

Request Body

Field	Type	Required	Validation	Description
email	string	Yes	Must be a valid email address	The user's email address
password	string	Yes	Minimum 8 characters	The user's chosen password

Request Example

{
  "email": "[email protected]",
  "password": "securePassword123"
}

Responses

201 Created

User account was successfully created.

{
  "message": "User created successfully",
  "email": "[email protected]"
}

Field	Type	Description
message	string	Success confirmation message
email	string	The email address of the newly created account

400 Bad Request

The request body failed validation. The message field contains details about which fields failed and why.

{
  "message": "email: Invalid email; password: String must contain at least 8 character(s)"
}

Field	Type	Description
message	string	Semicolon-separated list of validation errors

409 Conflict

A user with the given email address already exists.

{
  "message": "User with this email already exists"
}

or

{
  "message": "Email already exists"
}

Field	Type	Description
message	string	Conflict description

500 Internal Server Error

An unexpected error occurred during user creation.

{
  "message": "Internal server error"
}

Example

curl -X POST http://settlex.luganodes.com/api/onboarding/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "myStrongPass99"
  }'

POST /api/onboarding/login

Authenticates a user with email and password, returning a JWT token on success.

Authentication: None

Request Body

Field	Type	Required	Validation	Description
email	string	Yes	Must be a valid email address	The user's email address
password	string	Yes	Minimum 8 characters	The user's password

Request Example

{
  "email": "[email protected]",
  "password": "securePassword123"
}

Responses

200 OK

Authentication successful. Returns a JWT token valid for 7 days, the user's email, and optionally their Canton party ID (if one has been created).

{
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "email": "[email protected]",
  "partyId": "party-abc123::1220abcd..."
}

Field	Type	Description
message	string	Success confirmation message
token	string	JWT token for authenticating subsequent API requests
email	string	The authenticated user's email address
partyId	string | undefined	The user's Canton ledger party ID (undefined if no party created yet)

400 Bad Request

The request body failed validation.

{
  "message": "email: Invalid email"
}

Field	Type	Description
message	string	Semicolon-separated list of validation errors

401 Unauthorized

The email does not match any registered user, or the password is incorrect. The same message is returned for both cases to prevent user enumeration.

{
  "message": "Invalid email or password"
}

Field	Type	Description
message	string	Generic authentication failure

500 Internal Server Error

An unexpected error occurred during authentication.

{
  "message": "Internal server error"
}

Example

curl -X POST http://settlex.luganodes.com/api/onboarding/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "myStrongPass99"
  }'

Example Response

{
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI2ODI1YzRhNmE4OGU1NTAwMTIzNDU2NzgiLCJlbWFpbCI6ImFsaWNlQGV4YW1wbGUuY29tIiwiaWF0IjoxNzE3MzEyMDAwLCJleHAiOjE3MTc5MTY4MDB9.abc123",
  "email": "[email protected]",
  "partyId": null
}

---

Party

POST /api/party/create

NOTE: This endpoint will take ~10 seconds to fulfill as it involves several ledger interactions sequentially.

Allocates a new internal party on the Canton Network ledger for the authenticated user. Each user can only have one party.

After successful allocation, the endpoint:

1

Grant ledger rights (readAs and actAs) to Settlex

If rights granting fails, the party assignment is rolled back to maintain consistency between the database and the ledger.

2

Creates a transfer preapproval contract on the ledger for your party.

Builds a transfer preapproval command (referencing the configured provider party and DSO party), and submits it. If preapproval creation fails, the endpoint returns 500 with the error details.

Authentication: Required (Bearer Token)

Request Body

No request body required. The user is identified from the JWT token.

Responses

200 OK

Party was successfully allocated on the ledger, assigned to the user, granted rights, and a transfer preapproval contract was created.

{
    "message": "Party created successfully",
    "partyId": "9a923fe2-35a8-45f5-bccc-24848a393004::12207b916c3752acac9902d845ee0340d3b66e8ce0d1e2a00b187d97b99b10c44529",
    "rightsGranted": {
        "newlyGrantedRights": [
            {
                "kind": {
                    "CanReadAs": {
                        "value": {
                            "party": "9a923fe2-35a8-45f5-bccc-24848a393004::12207b916c3752acac9902d845ee0340d3b66e8ce0d1e2a00b187d97b99b10c44529"
                        }
                    }
                }
            },
            {
                "kind": {
                    "CanActAs": {
                        "value": {
                            "party": "9a923fe2-35a8-45f5-bccc-24848a393004::12207b916c3752acac9902d845ee0340d3b66e8ce0d1e2a00b187d97b99b10c44529"
                        }
                    }
                }
            }
        ]
    },
    "transferPreapproval": {
        "updateId": "122074aa25376a3d5e7d4e70cc93d603625ba46582eef0e081f3fa45620d8dc2a1ca",
        "completionOffset": 1117206
    }
}

Field	Type	Description
message	string	Success confirmation message
partyId	string	The Canton Network party identifier allocated to the user
rightsGranted	object	The ledger rights granted to the party (structure from Canton SDK)
transferPreapproval	object	The result of submitting the transfer preapproval command (contains completionOffset and updateId)

400 Bad Request

Validation error.

{
  "message": "field: error description"
}

401 Unauthorized

Missing or invalid authentication token. See Authentication Failure Responses.

409 Conflict

The user already has a party assigned. This is checked both at the start and atomically during the update.

{
  "message": "Party already exists"
}

Field	Type	Description
message	string	Indicates the user already has a party on the ledger

500 Internal Server Error

Ledger allocation, rights granting, transfer preapproval creation, or an unexpected error occurred.

{
  "message": "Failed to allocate party"
}

or:

{
  "message": "Failed to grant ledger rights"
}

or (transfer preapproval failures):

{
  "message": "Failed to build transfer preapproval contract command"
}

{
  "message": "Failed to submit transfer preapproval contract command"
}

{
  "message": "Failed to create transfer preapproval contract for party"
}

or:

{
  "message": "Internal server error"
}

Field	Type	Description
message	string	Description of the server-side failure

Example

curl -X POST http://settlex.luganodes.com/api/party/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Example Response

{
  "message": "Party created successfully",
  "partyId": "party-abc123::1220abcdef0123456789abcdef0123456789",
  "rightsGranted": {
    "readAs": ["party-abc123::1220abcdef0123456789abcdef0123456789"],
    "actAs": ["party-abc123::1220abcdef0123456789abcdef0123456789"]
  },
  "transferPreapproval": {}
}

---

API Key

POST /api/api-key/create

Generates a new API key for the authenticated user. The raw key is generated using crypto.randomBytes(32) (64 hex characters) and is returned to the user only once. Each user can only have one active API key. If the user previously deactivated their key (via DELETE /api/api-key), calling this endpoint will reactivate with a freshly generated key.

Authentication: Required (Bearer Token)

Request Body

No request body required.

Responses

200 OK

API key was successfully generated and stored.

{
  "message": "Api key created successfully",
  "apiKeyRaw": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890"
}

Field	Type	Description
message	string	Success confirmation message
apiKeyRaw	string	The raw API key (64 hex characters). Store this securely — it cannot be retrieved again.

Important: The apiKeyRaw value is shown only once upon creation. We store only the key hash. If lost, a new key must be generated (after deleting the existing one, if applicable).

401 Unauthorized

Missing or invalid authentication token. See Authentication Failure Responses.

409 Conflict

The user already has an active API key. Only one active API key is allowed per user. Delete the existing key first before creating a new one.

{
  "message": "Api key already exists"
}

Field	Type	Description
message	string	Indicates a duplicate API key for this user

500 Internal Server Error

An unexpected error occurred during key generation or storage.

{
  "message": "Internal server error"
}

Example

curl -X POST http://settlex.luganodes.com/api/api-key/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Example Response

{
  "message": "Api key created successfully",
  "apiKeyRaw": "f47ac10b58cc4372a5670e02b2c3d479f47ac10b58cc4372a5670e02b2c3d479"
}

DELETE /api/api-key

Deactivates the authenticated user's API key. After deactivation, the user can generate a new key via POST /api/api-key/create.

Authentication: Required (Bearer Token)

Request Body

No request body required. The user is identified from the JWT token.

Responses

200 OK

The API key was successfully deactivated.

{
  "message": "Api key deleted successfully"
}

Field	Type	Description
message	string	Success confirmation message

401 Unauthorized

Missing or invalid authentication token. See Authentication Failure Responses.

404 Not Found

No active API key was found for the authenticated user. This occurs if the user never created a key or already deactivated it.

{
  "message": "Api key not found"
}

Field	Type	Description
message	string	Indicates no active API key exists for the current user

500 Internal Server Error

An unexpected error occurred during key deactivation.

{
  "message": "Internal server error"
}

Example

curl -X DELETE http://settlex.luganodes.com/api/api-key \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Example Response

{
  "message": "Api key deleted successfully"
}

---

Balance

GET /api/balance

Retrieves the available and reserved balance for the authenticated user's Canton party.

Authentication: Required (Bearer Token)

Request

No request body or query parameters required. The party is identified from the authenticated user's partyId.

Responses

200 OK

Balance successfully retrieved.

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

Field	Type	Description
balance	number	The available (spendable) balance for the user's party in Canton Coin (CC)
reservedBalance	number	The amount currently reserved (locked for pending operations) in Canton Coin

401 Unauthorized

Missing or invalid authentication token. See Authentication Failure Responses.

404 Not Found

The user's party was not found in the database. This can happen if the user has not yet created a party, or if the party record does not exist in the database.

{
  "message": "Party not found"
}

Field	Type	Description
message	string	Indicates no party record exists for this user

500 Internal Server Error

An unexpected error occurred while querying the balance.

{
  "message": "Internal server error"
}

Example

curl -X GET http://settlex.luganodes.com/api/balance \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Example Response

{
  "balance": 5000,
  "reservedBalance": 150.75
}