Documentation Index
Fetch the complete documentation index at: https://ventra.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
Anunnaki manages the country list centrally and updates it when the KGC adds or removes jurisdictions. Operators cannot edit the list directly. Production cutover will use MaxMind GeoIP2; sandbox runs against a deterministic stub resolver.
Sandbox uses a stub IP resolver covering ~20 IP prefixes for end-to-end testing. Unresolvable or private IPs return status_blocked with block_reason: "unresolvable_ip" or "private_ip".
The three tiers
| Tier | Meaning | Operator action |
|---|
status_allowed | Default for unlisted countries. | Continue signup. |
status_restricted | Country has its own license regime. | Route to compliance review. |
status_blocked | KGC-mandated ban. | Reject signup, show user_message. |
Currently blocked (KGC-mandated)
US, RU, BY, KP, IR, MM.
Currently restricted (local-license regimes)
UK, CA-ON, SE, NL, DE, FR, ES, IT, AU.
Endpoints
| Method | Path | Description |
|---|
POST | /v1/geo/check | Resolve IP → tier. |
GET | /v1/geo/countries | Full list with current tier values (Cache-Control: public, max-age=86400). |
POST /v1/geo/check
curl https://sandbox.api.anunnakielite.com/v1/geo/check \
-H "Authorization: Bearer cur_sk_test_EXAMPLEKEY123456789012345678901234" \
-H "Content-Type: application/json" \
-d '{
"ip_address": "203.0.113.42",
"user_agent": "Mozilla/5.0...",
"context": "signup"
}'
{
"status": "status_allowed",
"country_code": "FR",
"country_name": "France",
"region": "EU",
"ip_address": "203.0.113.42",
"checked_at": "2026-05-24T15:02:00Z"
}
{
"status": "status_blocked",
"country_code": "US",
"country_name": "United States",
"block_reason": "kgc_us_undertaking_2016",
"user_message": "Sorry, we are unable to accept players from your jurisdiction.",
"checked_at": "2026-05-24T15:02:00Z"
}
{
"status": "status_restricted",
"country_code": "GB",
"country_name": "United Kingdom",
"restriction_reason": "requires_local_license",
"user_message": "Service availability in your region is under review.",
"next_action": "queue_for_review"
}
X-Cache: HIT|MISS. The IP resolver is internally cached for 24h per (IP, country); unresolvable IPs are not cached. Every request — HIT or MISS — writes a row to the 7-year audit log.
GET /v1/geo/countries
{
"version": "2026-05-24",
"countries": [
{ "code": "US", "name": "United States", "status": "blocked" },
{ "code": "RU", "name": "Russia", "status": "blocked" },
{ "code": "GB", "name": "United Kingdom","status": "restricted" },
{ "code": "FR", "name": "France", "status": "allowed" }
]
}
Webhooks
| Event | Fires when |
|---|
geo.country_blocked | A country moves to blocked. |
geo.country_restricted | A country moves to restricted. |
geo.country_allowed | A country moves back to allowed. |
{
"event": "geo.country_blocked",
"event_id": "evt_geo_99f02a",
"timestamp": "2026-05-24T15:02:00Z",
"data": {
"country_code": "TR",
"country_name": "Turkey",
"previous_status": "allowed",
"new_status": "blocked",
"reason": "kgc_mandate_2026"
}
}
Operator policy
- Frequency: signup only. No per-login or per-transaction re-checks.
- VPN handling: none. Raw IP only.
- Audit: every check is retained for 7 years (KGC).
- Override: only Anunnaki compliance can grant case-by-case exceptions.
Error codes
| Status | Code |
|---|
| 400 | invalid_ip |
| 401 | unauthorized |
| 422 | unresolvable_ip (rare — treat as blocked) |
| 429 | rate_limited |
