Access API Contract / 2026-05-20

GCA Access API Contract

This page defines the controlled HTTPS API contract for the GCA account path. It covers email-only user registration, member account intake, read-only wallet verification, credit ledger records, GCA Member records, and support review statuses.

The Workers + D1 backend now exposes live public routes for member access and wallet verification. The 10,000 GCA member benefit is still manual review only, and no route sends tokens, requests wallet signatures, or creates live trading permission.

The backend is deployed on Cloudflare Workers + D1 at https://gca-registration-api.gcagochina.workers.dev, so the public registration and member access pages can write directly to D1. Source remains in cloudflare/gca-registration-worker/. A future api.gcagochina.com custom domain still requires Cloudflare access to the account that owns the gcagochina.com zone.

A local operator backend is also available for localhost testing, evidence export, read-only GCA balance checks, and operator review workflows. Implementation details are listed below in the endpoint contract and technical evidence sections.

Current Stage member access API live
Public Endpoint Email + member access live
Local Backend tools/gca_member_backend.py
Local Console operator.html
Account UI /gca/member-access/ live
Production Email API Cloudflare Workers + D1 live
API Base https://gca-registration-api.gcagochina.workers.dev
Admin Read Token protected
Admin Export tools/export_cloudflare_email_registrations.py
API Smoke Check tools/check_gca_registration_api.py
Public API Status api-status.html
Public API CI Check .github/workflows/check-gca-registration-api.yml
Local Ledger Sync tools/sync_cloudflare_email_registrations.py
Contact CSV Export tools/export_gca_email_contacts.py
Registration Ops tools/run_gca_registration_ops.py
Contact Suppression tools/suppress_gca_contact.py
Contact Suppression API /gca/contact-suppressions
Suppression Packet gca_contact_suppression_v1
Suppression Sync tools/sync_cloudflare_contact_suppressions.py
Suppression Migration cloudflare/gca-registration-worker/migrations/0002_contact_suppressions.sql
Future API Domain api.gcagochina.com pending zone access
Balance Read eth_call balanceOf
Member Access Version gca_member_access_v1
Service Request Version gca_service_request_v1
Service Request Migration cloudflare/gca-registration-worker/migrations/0005_service_requests.sql

Endpoint Contract

POST /gca/email-registrations

Live Cloudflare Workers + D1 email registration intake for the GCA user list. It requires an email and safety acknowledgements only; it does not request a wallet, signature, private key, seed phrase, payment, or exchange API secret.

GET /gca/email-registrations

Token-protected admin read for operator review. Public visitors cannot read the registration ledger.

POST /gca/contact-suppressions

Live public email do-not-contact request using gca_contact_suppression_v1. It records only an email, reason, source, and safety acknowledgements; no wallet, signature, transaction, private key, seed phrase, payment, or exchange API secret is requested.

GET /gca/contact-suppressions

Token-protected admin read for local suppression sync. Operators use tools/sync_cloudflare_contact_suppressions.py and the local ops pipeline before contact CSV export.

GET /gca/access-config

Live public access configuration for GCA thresholds, chain ID, contract address, ledger boundaries, and safety rules.

POST /gca/member-access

Live account intake for gca_member_access_v1. It stores email/account fields, verifies the Base wallet, and writes eligible credit/member ledger records.

POST /gca/wallet-verifications

Live read-only GCA balance checks using Base Mainnet eth_call and ERC-20 balanceOf.

GET /gca/credit-ledger

Token-protected admin read for account-level 100 GCA AI Quant Access credits records.

POST / GET /gca/service-requests

Prepared token-protected operator queue for requested GCA AI Quant Access service scope before delivery. Local backend support is implemented, the D1 migration is prepared, and wrangler deploy --dry-run passes. The 2026-06-18 readiness check also passed D1 visibility, but the Cloudflare Worker route remains non-live because cloudflare-auth-session and Worker deploy permission failed with error 10000. Post-deploy validation must run with --include-pending-routes. It records service ID, optional credit ledger ID, requested credit hold, and review status; it does not deduct credits, connect wallets, request signatures, send tokens, or create trading permission.

POST / GET /gca/credit-usage

Prepared token-protected operator ledger for reviewed service-level credit usage. Local backend support is implemented, the D1 migration is applied, and wrangler deploy --dry-run passes. The 2026-06-18 readiness check also passed D1 visibility, but the Cloudflare Worker route remains non-live because cloudflare-auth-session and Worker deploy permission failed with error 10000. Post-deploy validation must run with --include-pending-routes. It records service ID, credits used, before/after balance, and status; it never connects wallets, requests signatures, sends tokens, or creates trading permission.

GET /gca/member-ledger

Token-protected admin read for GCA Member ledger state, holding-period review, 10,000 GCA member benefit status, next refresh due date, and status.

POST /gca/support-review

Creates or updates support review records for manual review workflows.

GET /gca/member-review

Reads review status for the authenticated account after the controlled account UI exists.

POST /gca/member-review

Local-only operator path to append a manual support review status update. It writes to the local JSONL ledger only and never sends replies, writes production data, calls wallets, requests signatures, or transfers GCA.

POST / GET /gca/member-benefit-transfers

Local-only record path for manually completed reserve-wallet transfers. It verifies the public transaction hash with read-only Base receipt data, records matching GCA Transfer evidence, and never sends tokens.

GET /gca/operator-summary

Local-only console summary for email registration, pre-registration, wallet verification, credit ledger, member ledger, member benefit transfer, and support review counts. The localhost backend writes local JSONL ledger records for testing only.

GET /gca/operator-digest

Local-only redacted daily digest view created by tools/run_gca_daily_ops.py --build-digest. It returns public health, BaseScan preflight status, member ops counts, support queue counts, holding evidence counts, and next actions without user records, emails, admin tokens, signatures, or automatic transfers.

GET /gca/operator-action-plan

Local-only manual checklist derived from local ledger counts and the redacted operator digest. It ranks next actions and shows a redacted support preview; it never sends replies, writes production data, connects wallets, or transfers GCA.

GET /gca/review-package

Local-only reviewer evidence export for support and platform follow-up. It includes local ledger totals, latest records, recordManifest, packageDigestSha256, public reference links, and safety boundaries. Use ?redact=public before external sharing, tools/export_gca_review_package.py to export from local JSONL data without running the server, and tools/verify_gca_review_package.py to verify the digest.

Required Request Fields

Member accessemail, walletAddress, termsAccepted, no-secrets acknowledgement
Email registrationemail, contact consent, no-secrets acknowledgement
Contact suppressionemail, contactSuppressionRequested, no-secrets acknowledgement
Member evidencememberBenefitReviewEvidence, holdingStartDate, evidenceTxHash, evidenceTxHashFormatOk
Wallet verificationregistrationId, walletAddress, chainId, contractAddress
Service requestemail, serviceId, no-secrets acknowledgement, manual-review acknowledgement
Credit usagecreditLedgerId, serviceId, creditAmountUsed, admin token
Support reviewstatus, nextStep, reviewId or memberLedgerId / walletAddress
Ledger readsADMIN_READ_TOKEN protected operator read

Allowed Statuses

Intakereceived, wallet_pending, needs_more_information
Email registrationreceived
Contact suppressionsuppressed
Wallet checkverified, below_threshold, failed, expired
Credit ledgerqueued, ledger_recorded, partially_used, used, expired, revoked
Service requestqueued_operator_review, queued_missing_credit_ledger, queued_insufficient_credits
Credit usageusage_recorded, exhausted
Member ledgeractive, needs_refresh, below_threshold, paused, revoked
Member benefit10,000 GCA after 30-day hold review
Evidence reviewuser_supplied_pending_review, needs_more_information, eligible, transferred, contacted, waiting_for_user_evidence, closed

Required Controls

  • controlled HTTPS origin
  • public email registration and unsubscribe routes require only form acknowledgements
  • token-protected admin reads for Cloudflare registration and suppression records
  • token-protected admin reads for account-level ledger routes
  • CSRF protection for state-changing routes
  • website / company / homepage honeypot bot-trap fields on public forms
  • rate limits on pre-registration and wallet verification
  • structured audit logs for status changes
  • server-side validation of chain ID 8453 and the GCA contract address

Do Not Collect

  • Private key or seed phrase.
  • Exchange API secret.
  • Withdrawal permission.
  • Custody request or fund-transfer request.
  • One-time code or recovery phrase.
  • Any permission that bypasses risk controls.

API References

Use the readable API, review queue, operations, and ledger pages first. The user-facing production path is /gca/member-access/.

Canonical Identity

NetworkBase Mainnet / chainId 8453
Contract0x3197c42f4a06f7be32a9a742ac2a766f0ff682c6
Official poolGCA/USDT
Pool address0xfe6a598bf738d7eec9640897064ca3a490128d3d447ced96077aef8e9dd1c1d0
Quote assetBase USDT / 0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2