API_DOCUMENTATION.md¶

Garuda Chain API — Referensi Lengkap v1

Metadata
Base URL (Production)	`https://api.garudachain.id`
Base URL (Staging)	`https://api.staging.garudachain.id`
Base URL (Local)	`http://localhost:4000`
Versi API	v1
OpenAPI	`/api/v1/openapi.json` (partial — lihat dokumen ini untuk lengkap)
GraphQL	`POST /graphql` · Schema: `/api/v1/graphql-schema`
Terakhir diperbarui	2026-07-04

1. Autentikasi¶

1.1 Admin Auth¶

Header: x-admin-key: <ADMIN_API_KEY>

Digunakan untuk: /api/v1/admin/*, KYC admin, bridge automation, beberapa bridge inbound.

Jika ADMIN_API_KEY tidak diset: 503 (kecuali NODE_ENV=development + ALLOW_OPEN_ADMIN=true).

1.2 Wallet Auth (EIP-191)¶

Aktif jika NODE_ENV=production atau WALLET_AUTH_REQUIRED=true.
Nonaktif jika WALLET_AUTH_DISABLED=true.

Headers:

x-garuda-address: 0x...
x-garuda-timestamp: <unix_ms>
x-garuda-signature: <signed_message>

Message format:

Garuda Chain Authentication
Address: 0x...
Action: <action-string>
Timestamp: <unix_ms>
Body: <keccak256 of sorted JSON body>

TTL signature: 5 menit.

1.3 Public (tanpa auth)¶

Mayoritas GET chain/explorer, GNFT metadata, bridge status/quote, RPC proxy (method allowlist).

2. Middleware Global¶

Layer	Konfigurasi
Helmet	Security headers default
CORS	`CORS_ORIGIN` env (comma-separated); default `*`
Body limit	15 MB (KYC image upload)
Rate limit GET	2000 req/min
Rate limit POST	600 req/min
Rate limit bypass	Admin, KYC admin, `/community/`, `/accounts/`, `/garuda-pay/*`, GNFT RPC

3. Health & Meta¶

Method	Path	Auth	Deskripsi
GET	`/`	Public	Service info
GET	`/health`	Public	Health check `{ status, chain, version }`
GET	`/api/v1/openapi.json`	Public	OpenAPI spec (partial)
GET	`/api/v1/graphql-schema`	Public	GraphQL SDL
POST	`/graphql`	Public	GraphQL query

4. Chain & Explorer¶

Method	Path	Auth	Deskripsi
GET	`/api/v1/chain`	Public	Chain ID, block number, symbol
GET	`/api/v1/blocks/latest`	Public	Block terbaru
GET	`/api/v1/blocks/:number`	Public	Block by number
GET	`/api/v1/transactions/:hash`	Public	Tx + receipt + GDC/GIDR parse
GET	`/api/v1/accounts/:address`	Public	Balance multi-RPC + community claim summary
GET	`/api/v1/accounts/:address/transfers`	Public	GDC transfer scan

5. Network & GNFT¶

Prefix: /api/v1/network

Method	Path	Auth	Deskripsi
GET	`/`	Public	Network metadata aktif
GET	`/contracts`	Public	Registry alamat kontrak
GET	`/all`	Public	Semua network configs
GET	`/gnft/listings`	Public	Listing marketplace aktif
GET	`/gnft/listings/:tokenId`	Public	Listing per token
GET	`/gnft/collections`	Public	Katalog koleksi
GET	`/gnft/metadata/:tokenId`	Public	ERC-721 metadata JSON
GET	`/gnft/perks/:address`	Public	Perks holder (check-in boost, dll.)
GET	`/gnft/:address`	Public	Snapshot GNFT milik address

6. Validators¶

Prefix: /api/v1/validators

Method	Path	Auth	Deskripsi
GET	`/program`	Public	Config program validator
GET	`/`	Public	Daftar validator on-chain
GET	`/ranking`	Public	Ranking validator
GET	`/expansion`	Public	Status ekspansi komunitas
GET	`/applications/list`	Public	Daftar aplikasi validator
POST	`/applications`	Public ⚠️	Submit aplikasi validator
GET	`/:address`	Public	Detail validator

7. Garuda Pay¶

Prefix: /api/v1/garuda-pay

Method	Path	Auth	Deskripsi
GET	`/rails`	Public	Payment rails tersedia
GET	`/profile/:address`	Wallet	Profil Garuda Pay
GET	`/payments/:address`	Wallet	Riwayat pembayaran
POST	`/link`	Wallet	Link payment rail
DELETE	`/link`	Wallet	Unlink payment rail
POST	`/active-rail`	Wallet	Set rail aktif
POST	`/top-up`	Wallet	Top-up saldo IDR
POST	`/charge`	Wallet	Charge merchant (GDC/GIDR)
POST	`/transfer`	Wallet	P2P transfer antar wallet
GET	`/fiat/config`	Public	Config fiat deposit/withdraw
GET	`/fiat/requests/:address`	Wallet	Daftar request fiat
POST	`/fiat/deposit`	Wallet	Buat request deposit
POST	`/fiat/withdraw`	Wallet	Buat request withdraw
GET	`/cs/config`	Public	Config customer support
GET	`/cs/tickets/:address`	Wallet	Tiket CS milik user
POST	`/cs/tickets`	Wallet	Buat tiket CS
POST	`/cs/tickets/:id/message`	Wallet	Kirim pesan ke tiket
GET	`/cs/tickets/:id/images/:messageId`	Wallet	Ambil gambar lampiran

8. KYC¶

Prefix: /api/v1/kyc

Method	Path	Auth	Deskripsi
GET	`/status/:address`	Wallet	Status KYC
POST	`/submit`	Wallet	Submit KYC Level 2 + dokumen
POST	`/mint-request`	Wallet	Request mint GNFT setelah KYC
GET	`/admin/queue`	Admin	Antrian review KYC
GET	`/admin/documents/:address/:kind`	Admin	Serve dokumen KYC
PATCH	`/admin/review/:address`	Admin	Approve/reject/suspend
POST	`/admin/mint-nft/:address`	Admin	Mint GNFT manual

Dokumen kinds: idFront, idBack, selfie, selfieWithIdBack, livenessExpression, livenessTurn

9. Community¶

9.1 Rewards¶

Prefix: /api/v1/community/reward

Method	Path	Auth	Action string
GET	`/status`	Wallet	`community:reward-status`
GET	`/check-in/prepare`	Wallet	`community:check-in-prepare`
POST	`/check-in`	Wallet	`community:check-in`
GET	`/claim/status`	Wallet	`community:claim-status`
POST	`/claim/prepare`	Wallet	`community:claim-prepare`
POST	`/claim/confirm`	Wallet	`community:claim-confirm`

Check-in flow: 1. GET /check-in/prepare → { nonce, expiresAt } 2. POST /check-in dengan body { address, nonce } + wallet auth

9.2 Programs (Missions & Referral)¶

Prefix: /api/v1/community

Method	Path	Auth	Deskripsi
GET	`/missions/status`	Wallet	Status misi
GET	`/referral/status`	Wallet	Status referral
POST	`/referral/bind`	Wallet	Bind kode referral
POST	`/referral/register`	Wallet	Register sebagai referrer
GET	`/overview`	Wallet	Gabungan reward + misi + referral

10. Bridge¶

Prefix: /api/v1/bridge

Method	Path	Auth	Deskripsi
GET	`/status`	Public	Status bridge keseluruhan
GET	`/assets`	Public	Daftar aset bridge
GET	`/float`	Public	Float relayer per chain
GET	`/quote`	Public	Quote biaya bridge
GET	`/fees`	Public	Fee schedule
GET	`/health/routes`	Public	Health per route
GET	`/capabilities`	Public	Kemampuan bridge
GET	`/projection`	Public	Proyeksi waktu/biaya
GET	`/reserves`	Public	Proof-of-reserves
GET	`/inbound/vaults`	Public	Alamat vault inbound
GET	`/chains`	Public	Chain destinasi didukung
GET	`/transfers`	Public	Daftar transfer (filter `?address=`)
GET	`/transfers/:transferId`	Public	Detail transfer
POST	`/sync`	Public ⚠️	Sync indexer outbound
POST	`/relay`	Public ⚠️	Trigger relayer outbound
POST	`/process`	Public ⚠️	Process pending transfers
POST	`/track`	Public ⚠️	Track transfer by ID
GET	`/automation/status`	Public	Status fee automation
POST	`/automation/run`	Admin	Jalankan fee automation
POST	`/inbound/sync`	Admin	Sync inbound indexer
POST	`/register-inbound`	Admin	Register inbound manual

Destinasi didukung: Ethereum (1), BSC (56), Polygon (137)

11. Wallet Utilities¶

Prefix: /api/v1/wallet

Method	Path	Auth	Deskripsi
POST	`/gas-aid`	Wallet	Auto top-up native gas

12. Admin¶

Prefix: /api/v1/admin (semua butuh x-admin-key)

Method	Path	Deskripsi
GET	`/ping`	Admin auth test
GET	`/stats`	Dashboard stats
GET	`/garuda-pay/overview`	Overview Garuda Pay
POST	`/garuda-pay/reset-balances`	Reset saldo (dev/staging)
GET	`/garuda-pay/fiat/requests`	Daftar request fiat
POST	`/garuda-pay/fiat/requests/:id`	Approve/reject fiat
GET	`/garuda-pay/cs/templates`	Template balasan CS
GET	`/garuda-pay/cs/tickets`	Semua tiket CS
POST	`/garuda-pay/cs/tickets/:id/reply`	Balas tiket
POST	`/garuda-pay/cs/tickets/:id/resolve`	Resolve tiket
GET	`/garuda-pay/cs/images/:ticketId/:messageId`	Gambar CS
GET	`/validators/applications`	Aplikasi validator
PATCH	`/validators/applications/:id`	Review aplikasi
GET	`/validators/program`	Program config
GET	`/tokenomics`	Token allocation
GET	`/community/rewards`	Community reward admin
POST	`/community/release-vault`	Release vault rewards
GET	`/account/:address`	Lookup akun lengkap

13. RPC Proxies¶

13.1 Hub Chain (read-only)¶

POST /api/v1/rpc

Method allowlist: eth_chainId, eth_blockNumber, eth_getBalance, eth_getTransactionCount, eth_getCode, eth_call, eth_estimateGas, eth_getBlockByNumber, eth_getBlockByHash, eth_getTransactionByHash, eth_getTransactionReceipt, eth_getLogs, net_version

Tidak termasuk: eth_sendRawTransaction

13.2 GNFT Chain (read + write)¶

POST /api/v1/rpc/gnft

Sama seperti hub + eth_sendRawTransaction untuk UX wallet GNFT.

14. Response Codes Umum¶

Code	Arti
200	Sukses
400	Validasi gagal / bad request
401	Wallet auth invalid / expired
403	Admin key invalid
404	Resource tidak ditemukan
429	Rate limit
503	Service unavailable (mis. admin key tidak dikonfigurasi)

15. Environment Variables (API)¶

Variable	Fungsi
`API_PORT`	Port (default 4000)
`GARUDA_NETWORK`	Network name (`mainnet`, `public-testnet`, dll.)
`GARUDA_RPC_URL`	Primary RPC
`GNFT_RPC_URL`	GNFT/Anvil RPC
`ADMIN_API_KEY`	Admin authentication
`DEPLOYER_PRIVATE_KEY`	Operator key (mint, bridge, dll.)
`GARUDA_PAY_OPERATOR_KEY`	Garuda Pay settlement
`BRIDGE_OUTBOUND_RELAYER_KEY`	Bridge relayer
`CLAIM_SIGNER_KEY`	Community claim EIP-712 signer
`CORS_ORIGIN`	Allowed origins
`WALLET_AUTH_REQUIRED`	Force wallet auth
`GARUDA_PAY_STORE_PATH`	Override path store JSON

16. Endpoint Berisiko (Perlu Hardening)¶

Endpoint	Risiko	Rekomendasi
`POST /bridge/relay`	Trigger relayer tanpa auth	Admin key atau signed relayer token
`POST /bridge/process`	Side effect tanpa auth	Sama
`POST /validators/applications`	Spam / disk write	Rate limit + captcha
`POST /graphql`	Query abuse	Auth atau query depth limit
Rate limit bypass `/garuda-pay/*`	Abuse payment	Granular per-user limit

Detail: SECURITY_AUDIT.md

17. Referensi¶

OpenAPI partial: docs/openapi.yaml
Implementasi: apps/api/src/
Wallet client auth: apps/wallet/src/lib/walletAuth.ts
DATABASE_SCHEMA.md