01Overview

The DojangScore API is a thin, authenticated read-layer over the DojangScoreV2 contract on GIWA. It converts on-chain attestations (Upbit KYC via Dojang, verified balance, account age, verified code) plus on-chain behaviour into a single 0–1000 trust score with a tier and a provenance ceiling.

Use it to gate, weight, or price anything off-chain: launchpad allocations, airdrop multipliers, trading fees, remittance limits, quest rewards. For settlement-critical logic, read the contract on-chain instead (see On-chain vs API).

02Quickstart

Three steps to a live score.

1 · Get a key (instant)

Issue a free trial key instantly — no email, no wait:

curl -X POST https://giwa-defi-suite.vercel.app/api/keys/trial \
  -H "content-type: application/json" \
  -d '{"project":"my-launchpad"}'

Returns a key — 1,000 free testnet calls · 60 req/min · upgrade nudge at 900. Keep the key server-side. Subscribe for more at proven.defi@gmail.com.

2 · Make your first request

curl -H "x-proven-key: YOUR_KEY" \
  https://giwa-defi-suite.vercel.app/api/score/0xE5EFB15259292F5B60A1DB074B708712998dB147

const res = await fetch(
  "https://giwa-defi-suite.vercel.app/api/score/0xE5EF…B147",
  { headers: { "x-proven-key": process.env.PROVEN_KEY } }
);
const score = await res.json();
console.log(score.tierName, score.score);

import requests
r = requests.get(
  "https://giwa-defi-suite.vercel.app/api/score/0xE5EF…B147",
  headers={"x-proven-key": PROVEN_KEY})
print(r.json()["tierName"], r.json()["score"])

3 · Read the response

score is the clamped 0–1000 value, tierName the band, ceilingProvenance the strongest proof class, and fees the on-chain discounts the tier unlocks. Full schema under GET /score.

03Authentication

Every request requires the x-proven-key header. Missing or invalid keys return 401.

Responses include rate-limit headers (X-RateLimit-Limit, -Remaining, -Reset) so you can throttle client-side. See Rate limits.

04Core concepts

The score is a sum of capped provenance contributions, clamped by a ceiling. Understanding both is the whole model.

Tiers & on-chain fees

The same tier that the API reports is what the on-chain contracts charge — so an off-chain gate and the on-chain fee always agree.

Provenance & the ceiling

Returns the full trust breakdown for a wallet.

Path parameters

Response · 200

curl -H "x-proven-key: $PROVEN_KEY" \
  .../api/score/0xADDRESS

const { score, tierName, ceilingProvenance, provenance } =
  await (await fetch(URL, { headers: H })).json();

if (ceilingProvenance === "ATTESTER")   // regulated — full trust
else if (score >= 200)                  // behavioural floor

d = requests.get(URL, headers=H).json()
if d["ceilingProvenance"] == "ATTESTER": ...

Lightweight tier + fee lookup when you don't need the full breakdown.

Liveness + chain head. No key required.

Score up to N addresses in one call for airdrop / allowlist sweeps.

Returns { results, count, failed }. Malformed entries or lookup failures come back as { address, error } without failing the overall batch. Each valid address counts as one call toward your quota.

curl -X POST -H "x-proven-key: $PROVEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"addresses":["0xADDRESS1","0xADDRESS2"]}' \
  .../api/score/batch

const res = await fetch(URL, {
  method: "POST",
  headers: { "x-proven-key": KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ addresses: ["0xADD1", "0xADD2"] })
});
const { results, count, failed } = await res.json();
console.log(`Scored ${count - failed} addresses`);

05Errors

Error bodies are { "error": "message", "code": "…" }.

06Rate limits & caching

Responses are cached for 45 seconds per address; cached:true tells you a value came from cache. For most gating use-cases 45s staleness is irrelevant; for settlement, read on-chain.

07Performance · measured on live deployment

Measured 2026-08-27 · GIWA Sepolia (chainId 91342) · 10–15 sequential requests each

Cached reads return in under 300 ms. Cold reads include an RPC round-trip to GIWA Sepolia. Times measured from a single origin; your latency may vary by region.

08Playground · reads the chain live, no key needed

This reads DojangScoreV2 directly over public RPC — the same source the API caches — so you can verify any wallet right now.

08Playbooks

Drop-in gating patterns. Each is a few lines because the hard part (provenance) is already on-chain.

Launchpad · sybil-resistant allocation

// Only wallets with a real proof get an allocation; weight by tier.
const s = await score(addr);
if (s.ceilingProvenance === "NONE")        reject();          // no proof, no alloc
const mult = [0, 1, 1.5, 2][s.tier];       // Standard..Platinum
alloc = base * mult;

Airdrop · tier multipliers

const MULT = { Standard:1, Silver:1.25, Gold:1.5, Platinum:2 };
payout = base * MULT[s.tierName];

Payments / remittance · tiered limits

const DAILY = { Standard:500, Silver:2500, Gold:10000, Platinum:50000 };
limit = DAILY[s.tierName];

Quests · gate high-value tasks

if (s.tier >= 1) unlock("high-value quest");  // Silver+

09On-chain vs API

Contract: 0xDe9De6f3d4a50BF414927EF6D523aFa65355492a (DojangScoreV2). Minimal ABI:

["function score(address) view returns (uint16)",
 "function tierOfWallet(address) view returns (uint8)",
 "function scoreBreakdown(address) view returns (tuple(uint16,uint16,uint16,uint16,uint16,uint16,uint8,uint16,uint8,bool,bool))"]

10Roadmap

11Get a key

Instant trial (recommended)

Issue yourself a key in seconds — no signup, no email. One command:

curl -X POST https://giwa-defi-suite.vercel.app/api/keys/trial \
  -H "content-type: application/json" \
  -d '{"project":"my-launchpad"}'

You'll receive:

Check your usage at any time:

curl -H "x-proven-key: YOUR_KEY" \
  https://giwa-defi-suite.vercel.app/api/keys/usage