AWMC Gateway Public API (Billing Info)

For end users: how to call the public APIs and when Tokens are charged. This page does not cover internals.

Platform

Platform: https://api.wmc.pub

Docs: https://wiki.awmc.team/dev/awmc-api

Sign in with your AWMC passport (forum account), then create a gw_ token in the dashboard (or use the login JWT).

Authentication

Send on every business request:

Authorization: Bearer <token>

• Browser JWT after login, or a long-lived gw_ token from the dashboard (keep it secret).

Buy Tokens

Top up via card-code redeem. Cards are sold at: https://store.awmc.cc/item?id=98
Redeem in the dashboard, or POST /redeem with a login token.

keychip

keychip is injected by the gateway. Callers must not send it. Only pass business fields such as qrcode.

1. Base URL and Paths

All business paths are under the gateway root with prefix /v1.

• GET: usually no body (health, charge queue).
• POST: JSON body with Content-Type: application/json.
• Upstream responses are often { "code": 0, "msg": "..." }. Some msg values are JSON strings and need a second JSON.parse.

2. Token Billing

• "Cost" below is charged when the response is HTTP 2xx and business succeeds (typically code === 0). 0 means free.
• Insufficient balance → 403 Insufficient balance.

Method	Path	Cost	Notes
GET	/v1/health	0	Upstream health check
POST	/v1/user/data	1	Detailed user data
POST	/v1/user/region	1	Region / rank
POST	/v1/user/music	2	All chart scores (large)
POST	/v1/user/charge	1	Ticket / charge query (read-only)
GET	/v1/charge/queue	0	Your filtered charge queue
POST	/v1/charge	10	Enqueue charge task
POST	/v1/update-lx	5	Upload scores to Lxns
POST	/v1/update-fish	5	Upload scores to DivingFish

Charge binding & queue

1. POST /v1/charge requires qrcode and charge.
2. After a successful enqueue, the gateway calls user/data with the same qrcode (free) to resolve userId and bind it to your gateway account.
3. GET /v1/charge/queue returns only tasks for your bound userId, with qrToken removed.

3. Interactive Demos

Set a valid token under Auth, then run the demos below.

3.1 Health (free)

GETHealth check

/v1/health▼

3.2 User queries (billed / JSON body)

All POST with body field qrcode.

POSTUser detailed data

/v1/user/data▼

3.3 Charge enqueue & queue

POSTEnqueue charge

/v1/charge▼

3.4 Score upload (billed / JSON body)

POSTUpload to Lxns

/v1/update-lx▼

4. Public JSON Catalog

GET https://api.wmc.pub/api/docs

Returns path, method, cost, and short descriptions for scripting.

5. Usage & Failure Rate

5.1 Usage stats (auth required)

Method	Path	Description
GET	/me/usage	Paginated call log (limit / offset)
GET	/me/usage/stats	Daily aggregates; days = 7 / 14 / 30 (default 7)

5.2 Failure rate (30-minute buckets)

Method	Path	Auth	Scope
GET	/usage/failure-rate	None	Site-wide
GET	/me/usage/failure-rate	Bearer token	Current user

GET https://api.wmc.pub/usage/failure-rate
GET https://api.wmc.pub/me/usage/failure-rate

• Window: fixed last 7 days
• Resolution: fixed 30-minute buckets (336 points; empty buckets filled with zeros)
• Scope field: response includes scope: global (site-wide) or user (personal)
• Logged field: upstreamCode from response body (code, else returnCode / returncode)

Definitions

Field	Meaning
codeZero	upstreamCode === 0 (business success)
businessFail	HTTP 2xx with non-zero upstreamCode
serverError	httpStatus === 0 (forwarding error) or httpStatus >= 500
clientError	HTTP 4xx
successRate	codeZero / calls
failureRate	(businessFail + serverError) / calls

Sample response (truncated)

{
  "scope": "global",
  "days": 7,
  "bucketMinutes": 30,
  "since": "2026-07-14T06:00:00.000Z",
  "until": "2026-07-21T05:30:00.000Z",
  "series": [
    {
      "ts": "2026-07-14T06:00:00.000Z",
      "bucketUnix": 1720936800,
      "calls": 12,
      "codeZero": 10,
      "businessFail": 1,
      "serverError": 1,
      "clientError": 0,
      "successRate": 0.8333,
      "failureRate": 0.1667
    }
  ],
  "summary": {
    "calls": 1200,
    "codeZero": 1100,
    "businessFail": 50,
    "serverError": 30,
    "clientError": 20,
    "successRate": 0.9167,
    "failureRate": 0.0667
  }
}

Note

Logs written before this feature may lack upstreamCode; they will not count toward codeZero / businessFail, but may still contribute to serverError / clientError via HTTP status.
Admins can also call GET /admin/usage/failure-rate (same data as the site-wide endpoint).

6. Common Errors

HTTP	Meaning
401	Missing or invalid token
403	Insufficient balance, etc.
404	Unknown path
500	Forwarding / misconfiguration; see msg
5xx	Retry later

Tips

Start with /v1/health (free). Use /v1/charge then /v1/charge/queue to track top-ups.
Legacy paths such as /v1/get_preview and /v1/upload_b50 are removed—use the table above.