List supported countries
GET /capabilities/countries - Read country capability data for the current environment and partner configuration.
0Gate is the primary public integration path for hosted payment, ramp, and swap experiences. Keep secret-key operations on your server and hand only browser-safe values to the widget.
Endpoint
| Field | Value |
|---|---|
| Method | GET |
| Path | /v1/capabilities/countries |
| Area | Capabilities |
| Operation id | listCountries |
| Auth boundary | Secret key from your server. |
Use it for
Read the country capability catalog for the active environment — each country's ISO code, display name, default fiat, and whether it is a supported on/off-ramp corridor. Use it to build a country picker or to confirm, server-side, that a user's country is supported before you create a session.
Use this endpoint only for discovery. It is read-only and never moves money, locks a quote, or creates a session.
This is the catalog, not a geo probe
Unlike the other capability routes, /capabilities/countries does not fall back to the caller's edge geo — that would collapse the catalog to a single country. To probe whether a specific user's region is eligible, use GET /capabilities/eligibility instead.
Production rules
- Keep secret keys on your server. This endpoint requires an
sk_*key; a publishablepk_*key can only call embed-bootstrap. - Validate a user's country on your server against
supported: truebefore creating a session. - This list is returned in full —
has_moreis alwaysfalse. Narrow it with thecountry_codeandsupportedquery params rather than paging. - Branch on machine-readable fields (
country_code,supported) and theX-Request-Idheader, not on display names. - Treat examples and placeholder values as fake data only.
Request
This is a GET with no body. All inputs are query parameters.
| Parameter | In | Required | Type | Use it for |
|---|---|---|---|---|
country_code | query | No | string (ISO 3166 alpha-2) | Look up a single country by its two-letter code. Case-insensitive. |
supported | query | No | "true" | When set to true, return only supported corridors. Any other value is ignored. |
Response
Returns the shared list envelope. Each element of data is a country object.
| Field | Type | Description |
|---|---|---|
object | string | Always list. |
data | array | The matching country objects (see below). |
has_more | boolean | Always false. Capability lists are returned in full, not paged. |
url | string | Static path of this resource. Does not echo query params. |
Country object
| Field | Type | Description |
|---|---|---|
object | string | Always country. |
country_code | string | ISO 3166-1 alpha-2 code, for example GB. |
name | string | Display name for the country. |
default_currency | string | The country's default fiat (ISO 4217), for example GBP. |
supported | boolean | true when the country is a supported on/off-ramp corridor. |
Examples
curl 'https://gate-api.0bit.app/v1/capabilities/countries?supported=true' \
-H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"{
"object": "list",
"data": [
{
"object": "country",
"country_code": "GB",
"name": "United Kingdom",
"default_currency": "GBP",
"supported": true
}
],
"has_more": false,
"url": "/v1/capabilities/countries"
}Errors
All errors use the unified envelope and carry an X-Request-Id response header. Branch on code/type/statusCode, not on the free-form message.
{
"type": "unauthorized",
"code": "unauthorized",
"message": "Example auth error using fake data.",
"request_id": "req_test_000000000123",
"doc_url": null,
"statusCode": 401
}| Status | type | When it happens |
|---|---|---|
401 | unauthorized | Missing or invalid secret key. |
429 | rate_limited | Request throttled. Back off and retry. |
5xx | server_error | Transient server or upstream failure. Retry with backoff. |
An unknown country is not an error
A country_code filter that matches nothing returns 200 with an empty data array, not a 404. Branch on the array length.
Related pages
List supported currencies
Read fiat currency capability data, optionally filtered by country.
Check 0Gate eligibility
Probe whether a specific user's region is eligible.
List supported assets
Read the crypto asset capability catalog.
Errors
Handle the unified error envelope, request ids, and retries.
Public boundary
This reference covers partner-scoped capability discovery. Internal operations, administrative routes, settlement venues and providers, and unsupported availability claims are outside the public API contract.