GX Protocol API Reference

8 specialised microservices. OpenAPI 3.0 specifications. Enterprise-grade authentication. Build on the full-stack economic operating system with comprehensive REST APIs designed for scale.

REST + JSONOpenAPI 3.0JWT + OAuth2CQRS AsyncIdempotent

API Services

Each service owns a bounded domain and exposes a focused set of endpoints. All services share common authentication, error handling, and pagination patterns.

Authentication & SSO

svc-auth

Unified OAuth2 Identity Provider with PKCE, session management, 15-minute access tokens with 7-day rotating refresh tokens, and multi-context account switching.

Auth

Public (login) / JWT Bearer

Key Endpoints
  • POST/auth/login
  • POST/auth/refresh
  • POST/auth/logout
  • GET/auth/sessions
  • GET/auth/contexts
  • GET/oauth/authorize
  • POST/oauth/token

Identity & KYC

svc-kyc

Privacy-preserving identity verification with document upload, multi-step KYC workflows, face verification, and attribute-based queries without exposing personal data.

Auth

JWT Bearer

Key Endpoints
  • POST/kyc/documents
  • GET/kyc/status/:profileId
  • POST/kyc/face-verification
  • GET/kyc/verify-attribute

Tokenomics & Payments

svc-tokenomics

Core

Core value transfer layer. Execute GX transfers, query wallet balances, retrieve transaction histories, and manage genesis distribution — all with CQRS async processing and idempotency guarantees.

Auth

JWT Bearer

Key Endpoints
  • POST/transfers
  • GET/wallets/:profileId/balance
  • GET/wallets/:profileId/transactions
  • POST/genesis
  • GET/treasury/:countryCode/balance

Government Treasury

svc-government

Public

Sovereign treasury management with public transparency endpoints. No authentication required for public data — treasury balances, disbursement histories, and economic statistics by country.

Auth

Public (read) / JWT Bearer (write)

Key Endpoints
  • GET/public/treasuries
  • GET/public/treasuries/:countryCode
  • GET/public/treasuries/:countryCode/disbursements
  • GET/public/treasuries/:countryCode/statistics
  • POST/api-credentials/treasury/:id

Governance

svc-governance

On-chain governance for protocol evolution. Submit proposals, cast votes programmatically, and execute approved changes. Public read access to all active proposals and voting results.

Auth

Public (read) / JWT Bearer (write)

Key Endpoints
  • GET/proposals
  • GET/proposals/:proposalId
  • POST/proposals
  • POST/proposals/:proposalId/vote
  • POST/proposals/:proposalId/execute

Lending & Capital

svc-loanpool

Interest-free loan pool with credit-score-driven eligibility. Loan applications, multi-step approval workflows, repayment tracking, and borrower history — integrated with the 6-component credit scoring engine.

Auth

JWT Bearer

Key Endpoints
  • POST/loans
  • GET/loans/:loanId
  • POST/loans/:loanId/approve
  • GET/users/:borrowerId/loans

Organizations & Multi-Sig

svc-organization

Multi-signature institutional accounts with configurable authorization rules. Propose organizations, endorse membership, define signing thresholds, and execute multi-party transactions with three-eyes-minimum approval.

Auth

JWT Bearer

Key Endpoints
  • POST/organizations
  • POST/organizations/:orgId/endorse
  • POST/organizations/:orgId/activate
  • POST/organizations/:orgId/rules
  • POST/organizations/:orgId/transactions
  • POST/transactions/:pendingTxId/approve

Credit Scoring & Trust

svc-trust

Dynamic credit scoring with 6 weighted components (trust, transactions, repayment, KYC, account maturity, velocity compliance). Consent-driven data sharing with FSPs, dispute resolution, and admin-configurable scoring parameters.

Auth

JWT Bearer

Key Endpoints
  • GET/credit-score/:participantId
  • GET/credit-score/:participantId/breakdown
  • GET/credit-score/:participantId/history
  • POST/credit-score/consent/grant
  • POST/credit-score/consent/revoke
  • POST/credit-score/disputes
  • POST/credit-score/disputes/:id/resolve

Authentication

Three authentication methods support different integration patterns — from participant-facing applications to service-to-service communication and cross-application SSO.

JWT Bearer Token

For participant and admin applications

Authorization: Bearer <access_token>

15-minute access tokens with 7-day rotating refresh tokens. Obtain via /auth/login, refresh via /auth/refresh with replay detection.

API Key + Secret

For service-to-service integrations

X-API-Key: <key> / X-API-Secret: <secret>

Provisioned per treasury or institution. Generate via /api-credentials endpoints. Supports credential rotation and revocation.

OAuth2 with PKCE

For SSO integrations between applications

Authorization Code Flow with PKCE

Full OAuth2 authorization code flow with PKCE challenge. Supports cross-application SSO between Wallet App and Command Center.

Common Patterns

All GX Protocol APIs follow consistent patterns for reliability, consistency, and developer experience.

CQRS Async Processing

Financial write operations return a commandId immediately. Poll GET /commands/:commandId/status for PENDING → CONFIRMED or FAILED.

Idempotency Keys

All write operations accept X-Idempotency-Key header. Duplicate requests with the same key return the original result without re-processing.

Cursor Pagination

List endpoints support ?page=1&limit=20 parameters. Responses include total count and pagination metadata.

Structured Errors

All errors return { success: false, error: { code, message, statusCode } }. Domain-specific error codes for programmatic handling.

Rate Limits

Endpoint CategoryLimitWindow
Login5 requestsper minute
Token Refresh20 requestsper minute
OAuth Authorize20 requestsper minute
OAuth Token Exchange10 requestsper minute
Credit Score Recalculation1 requestper 60 minutes
Credit Disputes3 disputesper 90 days
Consent Grants10 requestsper hour
General API100 requestsper 10 minutes

Ready to Build?

All chartered partners receive dedicated engineering support, sandbox environment access, and comprehensive documentation for a seamless integration experience.

Full API DocumentationRequest Charter Briefing