The GX Protocol is more than a new currency; it is a new economic operating system. While the protocol core — its immutable chaincode and monetary policy — provides foundational stability, its value lies in the ecosystem of applications and services built upon it.

Our Application Programming Interfaces (APIs) are the gateways to this new world. They are the tools we provide to our chartered partners and institutional stewards, enabling them to build the foundational industries of this global economy. We operate on a clear "protocol vs. application" model: the GX Protocol Foundation maintains the core public utility, and our partners use our APIs to build the innovative, competitive services that define the future of commerce and finance.

The GX Protocol API ecosystem consists of 8 specialised microservices, each owning a bounded domain and exposing a focused set of REST endpoints. All services share common authentication, error handling, and pagination patterns, documented in OpenAPI 3.0 specifications.

• svc-auth (port 3041) — Authentication, sessions, OAuth2 SSO
• svc-kyc (port 3042) — Identity verification, document management
• svc-tokenomics (port 3044) — Transfers, balances, transactions, genesis
• svc-government (port 3045) — Government treasury management, public transparency
• svc-governance — Proposals, voting, execution
• svc-loanpool — Interest-free lending, credit-scored eligibility
• svc-organization (port 3046) — Multi-signature institutional accounts
• svc-trust (port 3047) — Credit scoring, consent management, disputes

Access to our APIs is structured in tiers, reflecting the role and commitment of each participant in the ecosystem.

• Public API (Available Now): Read-only endpoints that require no authentication, providing transparency into protocol operations:
  • GET /public/treasuries — List all active government treasuries
  • GET /public/treasuries/:countryCode — Treasury overview by country
  • GET /public/treasuries/:countryCode/disbursements — Disbursement history
  • GET /public/treasuries/:countryCode/statistics — Economic statistics
  • GET /proposals — Active governance proposals and voting results
  • GET /public/supply — Total and circulating token supply

• Chartered Partner API: A full-featured suite available exclusively to institutions that have acquired a Global, Regional, or National charter. This is the primary toolkit for building commercial services.
• Validator API: The most privileged tier, granted only to approved Validator institutions. Includes advanced governance functions and real-time economic data streams.

The protocol supports three authentication methods for different integration patterns:

For participant-facing and admin applications. Obtain tokens via /auth/login.

• Access token: 15-minute expiry, embedded in Authorization: Bearer <token> header
• Refresh token: 7-day expiry with rotation — each refresh returns a new token pair
• Replay detection: If a consumed refresh token is replayed, the entire session is revoked
• Session management: Participants can list, view, and revoke active sessions

For service-to-service and institutional integrations. Provisioned per treasury or institution.

• Headers: X-API-Key: <apiKey> and X-API-Secret: <apiSecret>
• Provisioning: POST /api-credentials/treasury/:treasuryId generates a key pair
• Revocation: DELETE /api-credentials/:credentialId immediately revokes access
• Validation: POST /api-credentials/validate for real-time credential verification

For cross-application SSO integrations.

• Full authorization code flow with PKCE challenge/verifier
• Supports cross-application SSO between Wallet App and Command Center
• Timing-safe PKCE comparison for security
• Rate limited: 20 requests per minute on /authorize

This suite is the engine for innovation, providing all the necessary tools to build sophisticated financial and commercial applications.

The foundational layer for value transfer on the blockchain.

• POST /transfers — Execute a GX transfer between participants (async CQRS — returns commandId)
• GET /wallets/:profileId/balance — Query participant wallet balance
• GET /wallets/:profileId/transactions — Transaction history with pagination (page, limit params)
• GET /treasury/:countryCode/balance — Country treasury balance
• POST /genesis — Genesis allocation distribution
• POST /wallets/:walletId/freeze — Freeze wallet (admin)
• POST /wallets/:walletId/unfreeze — Unfreeze wallet (admin)

CQRS Pattern: All financial write operations return a commandId immediately with status ACCEPTED. Poll GET /commands/:commandId/status for progression: PENDING → PROCESSING → CONFIRMED or FAILED.

A comprehensive identity, verification, and credit scoring stack.

• POST /auth/login — Authenticate and receive JWT token pair
• POST /auth/refresh — Rotate refresh token (opaque token with replay detection)
• POST /auth/logout — Revoke session
• GET /auth/sessions — List active sessions for current participant
• DELETE /auth/sessions/:sessionId — Revoke specific session
• GET /auth/contexts — Account context selector (personal, admin, institutional)

• POST /kyc/documents — Upload identity documents (multi-type: government ID, passport, proof of address)
• GET /kyc/status/:profileId — Check verification status (NONE → BASIC → ENHANCED → FULL)
• POST /kyc/face-verification — Biometric face check
• GET /kyc/verify-attribute — Privacy-preserving attribute query (returns true/false without exposing data)

• GET /credit-score/:participantId — Credit score summary (0-1000 score, tier, lending capacity)
• GET /credit-score/:participantId/breakdown — 6-component breakdown with sub-factors and improvement tips
• GET /credit-score/:participantId/history — Score history with trend analysis (period: 1m/3m/6m/1y/all)
• POST /credit-score/:participantId/recalculate — Manual recalculation (rate limited: 1 per 60 minutes)

Credit Scoring Components: Trust Score (25%), Transaction History (20%), Repayment History (20%), KYC Verification (15%), Account Maturity (10%), Velocity Compliance (10%). All weights are admin-configurable.

• POST /credit-score/consent/grant — Grant FSP access (scope: SCORE_AND_TIER or FULL_BREAKDOWN, max 365 days)
• POST /credit-score/consent/revoke — Immediate consent revocation (requires consentId + profileId)
• GET /credit-score/consent/active — List active FSP consents with access counts and expiry dates

• POST /credit-score/disputes — File dispute (rate limited: 1 active + 3 per 90 days, 7-day SLA)
• GET /credit-score/disputes/:disputeId — Dispute details and status
• POST /credit-score/disputes/:disputeId/resolve — Admin resolution (UPHELD/REJECTED/PARTIAL)

Interest-free lending with credit-score-driven eligibility tiers.

• POST /loans — Apply for an interest-free loan from the protocol loan pool
• GET /loans/:loanId — Loan details, status, and repayment schedule
• POST /loans/:loanId/approve — Approve loan application (admin)
• GET /users/:borrowerId/loans — Borrower loan history and active exposure

• Tier 1 (0-299): Not Eligible
• Tier 2 (300-499): Micro-Lending — max GX 10,000
• Tier 3 (500-699): Standard — max GX 100,000
• Tier 4 (700-849): Premium — max GX 1,000,000
• Tier 5 (850-1000): Institutional — no protocol ceiling

All tiers operate on a 95/5 profit share ratio.

Sovereign treasury management with public transparency and multi-signature controls.

• GET /public/treasuries — List all active government treasuries globally
• GET /public/treasuries/:countryCode — Treasury overview by country
• GET /public/treasuries/:countryCode/disbursements — Full disbursement history
• GET /public/treasuries/:countryCode/statistics?months=12 — Economic statistics with configurable time range

• POST /treasuries — Create government treasury (three-eyes minimum: initiator + approver + authoriser)
• Treasury transaction management with multi-signature approval workflows
• POST /api-credentials/treasury/:treasuryId — Generate API key pair for institutional integration
• GET /api-credentials/treasury/:treasuryId — List credentials for a treasury
• DELETE /api-credentials/:credentialId — Revoke credential immediately

On-chain governance for protocol evolution and community participation.

• GET /proposals — List active governance proposals (public, no auth required)
• GET /proposals/:proposalId — Proposal details including vote tally and status
• POST /proposals — Submit new proposal (requires verified participant with completed KYC)
• POST /proposals/:proposalId/vote — Cast vote on active proposal
• POST /proposals/:proposalId/execute — Execute approved proposal (admin only, requires quorum)

Multi-signature institutional accounts with configurable authorisation rules and three-eyes-minimum approval on all transactions.

• POST /organizations — Propose a new multi-signature organisation
• GET /organizations/:orgId — Organisation details, members, and rules
• POST /organizations/:orgId/endorse — Endorse membership (countersign)
• POST /organizations/:orgId/activate — Activate organisation after required endorsements
• POST /organizations/:orgId/rules — Define authorisation rules (signing thresholds, amount limits)
• POST /organizations/:orgId/transactions — Initiate a multi-party transaction
• GET /organizations/:orgId/transactions/pending — List pending transactions awaiting signatures
• POST /transactions/:pendingTxId/approve — Approve pending transaction (adds a signature)

This privileged suite is reserved for institutional stewards and focuses on governance and research capabilities.

• Economic Insights API: Real-time, aggregated, anonymised data streams on the health of the entire economy.
  • Key metrics: Capital velocity, transaction volume by sector, Gini coefficient, loan pool utilisation rates, cross-regional trade flows.
  • Value: An unprecedented source of primary data for economic research, modelling, and policy analysis.
• Governance API: Full programmatic access to the Validator Governance Council. Submit proposals, vote on protocol upgrades, and manage validator admission.

All GX Protocol APIs follow consistent patterns:

CQRS Async Processing: Financial write operations (transfers, loan applications, treasury transactions) are processed asynchronously. The API returns a commandId immediately. Poll for status: PENDING → PROCESSING → CONFIRMED or FAILED.

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

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

Error Responses: All errors follow a consistent format:

{
  "success": false,
  "error": {
    "code": "CREDIT_SCORE_NOT_FOUND",
    "message": "Credit score not found for participant",
    "statusCode": 404
  }
}

Domain-specific error codes enable programmatic handling. Error messages never expose sensitive information.

| Endpoint | Limit | Window | |----------|-------|--------| | Login | 5 requests | per minute | | Token Refresh | 20 requests | per minute | | OAuth Authorize | 20 requests | per minute | | Credit Score Recalculation | 1 request | per 60 minutes | | Credit Disputes | 3 disputes | per 90 days | | Consent Grants | 10 requests | per hour | | General API | 100 requests | per 10 minutes |

1. Charter Acquisition: The institution applies for and acquires a charter for a specific domain and geography, which includes the payment of the charter licence fee.
2. Execution of Agreements: The partner executes the legal Charter Agreement and a specific API Licence Agreement governing terms of use, security requirements, and acceptable use policies.
3. Technical Onboarding & Key Provisioning: Our dedicated partner engineering team works directly with your technical team to provision secure API keys and credentials.
4. Sandbox Environment Access: Partners receive access to a full-featured sandbox environment for rigorous development, testing, and integration without interacting with the live network.
5. Production Go-Live: Once your application passes all security and integration tests, you are cleared for production access on the main GX Protocol network.

All our partners receive access to:

• OpenAPI 3.0 specifications for all 8 microservices
• Comprehensive API reference with request/response examples
• Sandbox environment with full feature parity
• Dedicated engineering support for integration guidance
• Code samples in multiple languages

We invite the world's builders to join us. With these tools, you will not just be creating an application; you will be architecting the future of finance.