Phase 9: Developer API & Tooling

Panduan API, auto-config kontrak, dan health check lokal tanpa hosting.

Health Check

npm run dev:check

Memeriksa Anvil, API, Explorer, Landing, deploy kontrak, endpoint API, dan forge tests.

API: Auto Config

API membaca chain/deployments/{network}.json secara otomatis.

GARUDA_NETWORK=devnet npm run dev:api
# atau default:devnet

Endpoint baru

Method	Path	Deskripsi
GET	/api/v1/network	Network aktif
GET	/api/v1/network/contracts	Alamat kontrak
GET	/api/v1/network/all	Chain ID:devnet, testnet, mainnet
GET	/api/v1/openapi.json	Spesifikasi OpenAPI
GET	/api/v1/graphql-schema	GraphQL typeDefs

Contoh

curl http://localhost:4000/api/v1/network/contracts
curl http://localhost:4000/api/v1/chain
curl -X POST http://localhost:4000/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ chainStats { blockNumber chainId } }"}'

OpenAPI

Spesifikasi: docs/openapi.yaml

Impor ke Postman atau Insomnia, atau buka di https://editor.swagger.io

Docs lokal

npm run docs:preview

Pratinjau di http://localhost:8088. File cadangan: deploy/static/docs.html.

GraphQL Schema

query {
  chainStats { blockNumber chainId validatorCount totalStaked }
  latestBlock { number hash transactionCount }
  validators { address moniker stake commission }
  balance(address: "0x...")
}

Environment API

Variable	Default	Deskripsi
GARUDA_NETWORK	devnet	File deployment jaringan
GARUDA_RPC_URL	dari deployment	Override RPC
API_PORT	4000	Port API
RATE_LIMIT_MAX	100	Permintaan per menit

Alur developer

1. Jalankan layanan dengan npm run dev:stack
2. Verifikasi dengan npm run dev:check
3. Baca docs/openapi.yaml atau /api/v1/openapi.json
4. Integrasikan dengan @garuda-chain/sdk

Postman Collection

docs/postman/Garuda-Chain-API.postman_collection.json

1. Buka Postman, lalu Import file JSON
2. Set baseUrl = http://localhost:4000
3. Jalankan Health, Chain Info, lalu Validators

Opsional selanjutnya

• Swagger UI tertanam di API
• WebSocket untuk blok baru

Garuda Dev (merchant / developer portal)

Dokumentasi penuh: developer/garuda-dev.md

Base: /api/v1/garuda-dev
OpenAPI: docs/openapi.yaml (tag GarudaDev) lalu GET /api/v1/openapi.json

Paket API key (prabayar)

Paket	Biaya	Durasi
Bulanan	100 GDC	30 hari
3 Bulan	270 GDC	90 hari
Tahunan	900 GDC	365 hari

30% biaya dibakar (GET /api/v1/fees/burns). Key kedaluwarsa ditolak dengan 401.

Method	Path	Auth	Deskripsi
GET	/summary/:address	wallet	Dashboard Pay Platform, keys, webhooks
POST	/keys	wallet	Buat API key (gdk_…, secret sekali)
POST	/keys/revoke	wallet	Cabut API key
POST	/webhooks	wallet	Simpan URL sandbox
POST	/webhooks/test	wallet	Kirim event webhook.test
GET	/v1/dashboard	X-Garuda-Dev-Key	Dashboard merchant (dashboard:read)
GET	/v1/invoices	X-Garuda-Dev-Key	Daftar invoice (invoices:read) plus payUrl
POST	/v1/invoices	X-Garuda-Dev-Key	Buat invoice (invoices:write) plus payUrl

Quickstart: invoice, pay link, webhook

1. Di wallet Garuda Dev, beli paket dan buat API key. Simpan secret gdk_….
2. Simpan webhook sandbox dan secret webhook yang ditampilkan sekali.
3. Buat invoice:

curl -sS -X POST https://api.garudachain.id/api/v1/garuda-dev/v1/invoices \
  -H "Content-Type: application/json" \
  -H "X-Garuda-Dev-Key: gdk_…" \
  -d '{"customerLabel":"Pelanggan Toko","amountIdr":85000,"note":"Pesanan #42"}'

Respons berisi invoice.id dan invoice.payUrl. Kirim tautan itu ke pelanggan.

1. Setelah pembayaran sukses, server mengirim POST ke URL webhook Anda:

2. Events: payment.completed, invoice.paid, serta webhook.test dari tombol tes

3. Header: X-Garuda-Event, X-Garuda-Signature: sha256=<hmac>
4. Verifikasi (Node):

const crypto = require("crypto");
function verify(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const got = String(signatureHeader || "").replace(/^sha256=/, "");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got));
}

Gunakan raw request body (string UTF-8) untuk HMAC, bukan objek JSON yang di-parse ulang.