REST API Endpoints

All REST API endpoints are accessible through the API Gateway at http://localhost:4000/api/v1. Unless noted otherwise, all endpoints require a valid JWT Bearer token in the Authorization header.

Authentication

Method	Path	Description	Auth
POST	/auth/login	Authenticate and receive JWT token	No
POST	/auth/refresh	Refresh an expired access token	No
POST	/auth/revoke	Revoke a token	Yes
POST	/auth/mfa/setup	Initialize MFA for current user	Yes
POST	/auth/mfa/verify	Verify MFA code	Yes
GET	/auth/me	Get current user profile	Yes

Transactions

STR (Real-Time Gross Settlement)

Method	Path	Description	Permission
GET	/str/balance	Query STR reserve balance	str:balance:read
GET	/str/statement	Query STR statement	str:statement:read
POST	/transactions/str	Create STR transfer	transactions:create

TED (Same-Day Electronic Transfer)

Method	Path	Description	Permission
POST	/transactions/ted	Create TED transfer	transactions:create

DOC (Next-Day Credit Transfer)

Method	Path	Description	Permission
POST	/transactions/doc	Create DOC transfer	transactions:create

General Transaction Operations

Method	Path	Description	Permission
GET	/transactions	List transactions with filters	transactions:read
GET	/transactions/:id	Get transaction details	transactions:read
POST	/transactions/:id/cancel	Cancel a pending transaction	transactions:cancel

Query parameters for GET /transactions:

Parameter	Type	Description
type	string	Filter by type: STR, TED, DOC, LPI
status	string	Filter by status: created, submitted, settled, failed
date_from	date	Start date (ISO 8601)
date_to	date	End date (ISO 8601)
sender_ispb	string	Filter by sender ISPB
receiver_ispb	string	Filter by receiver ISPB
min_amount	decimal	Minimum amount
max_amount	decimal	Maximum amount
page	integer	Page number (default: 1)
page_size	integer	Items per page (default: 20, max: 100)

Securities

Method	Path	Description	Permission
GET	/securities/positions	List securities positions	securities:read
GET	/securities/positions/:id	Get position details	securities:read
POST	/securities/transfer	Transfer securities (SEL)	securities:transfer
POST	/securities/pledge	Pledge securities as collateral	securities:pledge
POST	/securities/release	Release pledged securities	securities:release
GET	/securities/trades	List CTP trades	securities:read
POST	/securities/trades	Register CTP trade	securities:trade

Settlements

Method	Path	Description	Permission
GET	/settlements/windows	List settlement windows and status	settlements:read
GET	/settlements/net-position	Query net position for current window	settlements:read
POST	/settlements/batch	Submit LDL batch	settlements:create
GET	/settlements/batches	List submitted batches	settlements:read
GET	/settlements/batches/:id	Get batch details and status	settlements:read

Forex

Method	Path	Description	Permission
GET	/forex/ptax	Get current PTAX rate	forex:read
GET	/forex/ptax/history	Get historical PTAX rates	forex:read
POST	/forex/contract	Register FX contract (CAM)	forex:create
GET	/forex/contracts	List FX contracts	forex:read
GET	/forex/contracts/:id	Get FX contract details	forex:read
GET	/forex/position	Get FX position report	forex:read

Query parameters for GET /forex/ptax:

Parameter	Type	Description
currency	string	Currency code (e.g., USD, EUR, GBP)
date	date	Rate date (default: today)

Cash Operations

Method	Path	Description	Permission
POST	/cash/order	Create cash order (CIR)	cash:create
GET	/cash/orders	List cash orders	cash:read
GET	/cash/balance	Get cash balance	cash:read
POST	/cash/deposit	Register cash deposit	cash:create

Data Extracts

Method	Path	Description	Permission
POST	/extracts	Request a data extract	extracts:create
GET	/extracts	List extract requests	extracts:read
GET	/extracts/:id	Get extract status	extracts:read
GET	/extracts/:id/download	Download extract file	extracts:download

Extract request body:

{
  "type": "transactions",
  "format": "csv",
  "filters": {
    "date_from": "2026-01-01",
    "date_to": "2026-01-31",
    "transaction_types": ["STR", "TED"],
    "status": ["settled"]
  }
}

Supported formats: csv, xlsx, json, xml

User Management

Method	Path	Description	Permission
GET	/users	List users in tenant	users:read
POST	/users	Create new user	users:create
GET	/users/:id	Get user details	users:read
PUT	/users/:id	Update user	users:update
DELETE	/users/:id	Deactivate user	users:delete
GET	/users/:id/roles	Get user roles	users:read
PUT	/users/:id/roles	Assign roles to user	users:roles:assign
GET	/roles	List available roles	roles:read
GET	/tenants/current	Get current tenant info	tenants:read

Common Response Format

All endpoints return responses in a consistent format:

Success Response

{
  "data": { },
  "meta": {
    "request_id": "req_01HQXYZ",
    "timestamp": "2026-01-15T10:30:00Z"
  }
}

Paginated Response

{
  "data": [],
  "meta": {
    "request_id": "req_01HQXYZ",
    "timestamp": "2026-01-15T10:30:00Z"
  },
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_entries": 245,
    "total_pages": 13
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Amount must be greater than zero",
    "details": [
      {
        "field": "amount",
        "message": "must be greater than 0"
      }
    ]
  },
  "meta": {
    "request_id": "req_01HQXYZ",
    "timestamp": "2026-01-15T10:30:00Z"
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request (validation error)
401	Unauthorized (missing or invalid token)
403	Forbidden (insufficient permissions)
404	Not Found
409	Conflict (duplicate or state conflict)
422	Unprocessable Entity (business rule violation)
429	Too Many Requests (rate limited)
500	Internal Server Error
503	Service Unavailable (downstream service down)