Configuration

Reference data for onboarding and payments. GET /v1/config/countries and GET /v1/maintenance are public; every other route requires x-api-key. Responses use the standard envelope documented in Responses and errors.

For API-key routes, auth failures occur before route handling: 403 for an invalid key and 429 when its rate limit is exceeded.

Endpoints#

Details#

GET /v1/config/bank#

Returns bank field definitions. countries is optional: omit it for all configurations, or provide a comma-separated list of ISO alpha-2 codes. Values are trimmed, uppercased, and deduplicated.

Success: 200.

{
	"success": true,
	"data": {
		"configurations": [
			{
				"country": "US",
				"fields": [
					{
						"key": "routingNumber",
						"label": "Routing Number",
						"required": true,
						"pattern": "^\\d{9}$",
						"placeholder": "123456789"
					}
				]
			}
		]
	}
}

Route errors: 400 empty, malformed, or unsupported country codes; 500 configuration retrieval failure.

GET /v1/config/chains#

No query or body. Returns every configured chain with nested token deployments. Success: 200.

{
	"success": true,
	"data": {
		"chains": [
			{
				"id": "chain-uuid",
				"slug": "ethereum",
				"name": "Ethereum",
				"chainId": 1,
				"image": null,
				"type": "EVM",
				"chainSpecifics": {},
				"createdAt": "2024-01-01T00:00:00.000Z",
				"tokens": [
					{
						"id": "token-uuid",
						"name": "USD Coin",
						"symbol": "USDC",
						"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
						"image": null,
						"accepted": true,
						"decimals": 6,
						"type": "stable",
						"metadata": {}
					}
				]
			}
		]
	}
}

For inverse nesting, use GET /v1/config/chains/tokens. Route errors: 500 chain retrieval failure. A token lookup failure for one chain is represented as an empty tokens array for that chain.

GET /v1/config/chains/tokens#

No query or body. Returns every configured token with nested chain deployments. Success: 200.

{
	"success": true,
	"data": {
		"tokens": [
			{
				"id": "token-uuid",
				"name": "USD Coin",
				"symbol": "USDC",
				"image": null,
				"accepted": true,
				"chains": [
					{
						"id": "chain-uuid",
						"slug": "ethereum",
						"name": "Ethereum",
						"chainId": 1,
						"image": null,
						"type": "EVM",
						"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
						"decimals": 6,
						"tokenType": "stable",
						"metadata": {}
					}
				]
			}
		]
	}
}

Route errors: 500 token retrieval failure. A chain lookup failure for one token is represented as an empty chains array for that token.

GET /v1/config/countries#

Public; no auth headers, body, or path parameters. By default, only countries with bank configuration are returned. The literal query all=true includes countries without banks; every other value behaves like omission.

Success: 200 with data: { countries }. Each country is { code, name, flag, language, currencies }; currencies is a string array or null. Route errors: 500 country retrieval failure.

GET /v1/config/countries/banks#

country is a required ISO alpha-2 query parameter; it is trimmed and uppercased. Success: 200.

{
	"success": true,
	"data": {
		"country": "US",
		"currencies": [
			{ "code": "USD", "symbol": "USD" },
			{ "code": "USN", "symbol": "USN" }
		],
		"banks": [
			{
				"slug": "jpmorgan-us",
				"name": "JPMorgan Chase",
				"code": "JPM"
			},
			{
				"slug": "bankofamerica-us",
				"name": "Bank of America",
				"code": "BOFA"
			}
		]
	}
}

The implementation sets symbol equal to the currency code. Route errors: 400 missing/malformed country; 404 country absent or has no banks; 500 retrieval failure.

GET /v1/config/username#

username is required. It must be at least four characters, contain only letters, digits, -, and _, and must not start with api_ (case-insensitive). Validation normalizes it to trimmed lowercase before lookup.

Success: 200 with data: { available: boolean }. Route errors: 400 missing/invalid username; 500 lookup failure.

GET /v1/maintenance#

Public; no auth headers, query, or body. Success is always 200 with data.status equal to ok, limited, or maintenance.

{
	"success": true,
	"data": {
		"status": "ok"
	}
}