> ## Documentation Index > Fetch the complete documentation index at: https://docs.globalstack.io/llms.txt > Use this file to discover all available pages before exploring further. # List currencies > List supported currencies with networks, directional transaction limits (inbound / outbound), capability flags (`can_onramp`, `can_offramp`, `can_deposit`, `can_convert`), and current conversion fees (`fees`) keyed by settlement network. Flag meaning depends on `type` — see the API overview. Each `fees.payment_methods` entry describes the tiered fee ladder and per-chain network fees for its settlement network, split by `offramp` / `onramp` when both directions are supported. `fees` is `null` for crypto currencies and when fee data is unavailable. Each row is unique by `code` plus `country_code` (for example every WAEMU country has its own `XOF` entry with its own networks and limits). Use filters to find currencies that support a given operation or network, then paginate with `page` and `per_page`. For which countries and networks we cover, start with `GET /v1/countries`. For banks and mobile money operators (`provider_id` on fiat beneficiaries), use `GET /v1/countries/{country_code}/providers` — not this resource. ### Platform view vs customer view Without `customer_id`, the capability flags answer "can this be done on the platform" — they are the same for every caller. Pass the optional `customer_id` query parameter (a customer id, `cust_…`) and the same flags answer a narrower question: can **this customer** do this right now? Capabilities that depend on the customer's state are downgraded — today, fiat `can_deposit` reads `false` when the customer's KYC is not approved. The capability filters (`can_deposit=true`, …) are then evaluated against the customer's view too, so a filtered listing never advertises an operation the customer would be blocked from. Every downgraded row carries a `customer_restrictions` array explaining the downgrade. Each entry has: - `capability` — the capability that was removed (e.g. `deposit`). - `reason` — a stable machine code (e.g. `customer_kyc_not_approved`). - `next_steps` — `{ action, docs_url }` with what to do about it. `customer_restrictions` entries are the exact diff between the platform view and the customer view: they appear **only** for capabilities the platform supports (`true` at platform level) that the customer's state removes. A capability that is `false` at platform level is never annotated, and the field is omitted entirely on rows with no downgrade and in the platform view. An unknown `customer_id`, or one belonging to another integration, returns 404 `not_found`; a malformed one returns 400 `invalid_input`. See the full [customer restrictions reference](https://docs.globalstack.io/api-reference/customer-restrictions) for all restriction reasons. ### Filter behavior - `code` — filter by ISO currency code (e.g. `XOF` returns all WAEMU country rows). - `type` — `fiat` or `crypto`. - `country_code` — filter by ISO 3166-1 alpha-2 country code. - `customer_id` — customer id (`cust_…`). Switches the listing to that customer's view (see above). - `can_onramp` — boolean. Currencies that can participate in onramps. For fiat, usable as onramp source; for crypto, as onramp destination. - `can_offramp` — boolean. Currencies that can participate in offramps. For fiat, usable as offramp destination; for crypto, as offramp source. - `can_deposit` — boolean. Currencies that can participate in deposits (typically crypto only). - `can_convert` — boolean. Currencies that participate in wallet-to-wallet conversions. - `network` — only currencies that include this network in their `networks` array. - `min_inbound_amount` — decimal string. Only currencies where at least one network has inbound min less than or equal to this value. - `max_inbound_amount` — decimal string. Only currencies where at least one network has inbound max greater than or equal to this value. - `min_outbound_amount` — decimal string. Only currencies where at least one network has outbound min less than or equal to this value. - `max_outbound_amount` — decimal string. Only currencies where at least one network has outbound max greater than or equal to this value. - `page` — integer, 1-indexed page number. - `per_page` — integer page size (max 200). ### Example ``` GET /v1/currencies?type=fiat&can_offramp=true ``` ## OpenAPI ````yaml /api-reference/openapi.json get /v1/currencies/ openapi: 3.0.0 info: title: GlobalStack API version: 1.0.0 description: > # Introduction GlobalStack API for cross-border payments powered by stablecoin rails. Getting started: authenticate with a Bearer token, make your first call to `GET /v1/currencies`, and explore. **Key operations:** - **Onramp** — convert external fiat into crypto credited to a wallet. - **Offramp** — convert crypto from a wallet into fiat delivered to a beneficiary. - **Conversion** — move value between two wallets belonging to the same customer. - **Transfer** — send crypto from a wallet to an external address. - **Deposit** — receive external crypto into a wallet via a deposit address. See the sections below for authentication, response shape, idempotency, references, metadata, and webhooks. ## Authentication All API requests require a Bearer token in the `Authorization` header: ``` Authorization: Bearer gsa_sk_live_your_api_key ``` API keys use the `gsa_sk_live_` prefix. API keys are scoped to a single merchant account. All resources created with a key belong to that merchant. Keep your keys secret — do not expose them in client-side code or public repositories. To rotate a key, generate a new one from your dashboard and update your integration before revoking the old key. ## API Response Shape Every response — success or failure — follows the same envelope: ```json { "status": true, "message": "Onramp created successfully", "code": "ok", "data": { }, "meta": { "request_id": "req_01ABC...", "timestamp": "2026-04-22T02:00:00Z", "version": "1" } } ``` **Fields:** - `status` (boolean) — whether the HTTP call succeeded. This is not the business status of the underlying resource. - `message` (string) — human-readable explanation for developers and logs. Do not show to end users. - `code` (string) — stable machine-readable result. `ok` on success, or an error code like `bad_request`. - `data` — the resource payload on success (object, array, or scalar). `null` on failure. - `meta` — request-scoped metadata, always present. Includes `request_id` (quote this in support tickets), `timestamp`, and `version`. On list endpoints, also includes `page`, `per_page`, `total`, `has_more`. On validation errors, includes `errors` array and `next_steps`. Error responses include `next_steps` in `meta` with an `action` string and a `docs_url` link: ```json { "status": false, "message": "Your request has validation errors.", "code": "bad_request", "data": null, "meta": { "request_id": "req_01ABC...", "timestamp": "2026-04-22T02:00:00Z", "version": "1", "errors": [ { "field": "amount", "code": "required", "message": "Amount is required." } ], "next_steps": { "action": "Review the request and retry with corrected parameters.", "docs_url": "https://docs.globalstack.io/errors#bad_request" } } } ``` ## Idempotency Pass an `Idempotency-Key` header on any create endpoint to make the request safely retryable: ``` Idempotency-Key: your-unique-key-here ``` **Rules:** - Same key + same body = returns the original response (no side effects). - Same key + different body = returns `idempotency_conflict` (409). - Keys are scoped to your merchant account. - Keys expire after 24 hours. Use idempotency keys for any operation that creates a resource or moves money. This protects against network retries, duplicate webhooks, and client-side retry loops. ## Rate Limits Requests over the rate limit are rejected with HTTP `429` and the error code `rate_limited`: ```json { "status": false, "message": "Too many requests. Slow down and retry shortly.", "code": "rate_limited" } ``` **Money-movement writes** (creating transfers, offramps, conversions, or wallet operations) are limited **per merchant account** — the budget is shared across all of your API keys and dashboard sessions. Reads are not limited. On a `429`, back off and retry with jitter; for money movement, reuse the same `Idempotency-Key` so the retry stays safe. ## Reference Every money movement operation (onramp, offramp, conversion, transfer) accepts an optional `reference` field — a merchant-supplied identifier that is unique per merchant account. ```json { "reference": "INV-2026-001", "wallet_id": "wal_..." } ``` If you omit `reference`, the API generates one automatically (prefixed `ref_`). References are unique per merchant — attempting to create two operations with the same reference returns the existing operation (same behavior as idempotency, but permanent and not time-limited). Use `reference` to correlate GlobalStack operations with your own system records (invoices, orders, payouts). ## Metadata Most create endpoints accept an optional `metadata` object — a flat set of string key/value pairs stored on the resource: ```json { "metadata": { "order_id": "ord_12345", "customer_email": "alice@example.com" } } ``` Metadata is returned on every GET response and in webhook payloads. It is not used by GlobalStack for processing — it exists for your own record-keeping. Resources that accept metadata: customers, wallets, senders, beneficiaries, wallet credentials, deposit addresses, onramps, offramps, conversions, and transfers. ## Webhook Signatures Every webhook delivery is signed so you can verify it came from GlobalStack and was not tampered with in transit. Signatures follow the [Svix](https://docs.svix.com/receiving/verifying-payloads/how) standard, so you can verify them with any Svix library — or manually with the construction below. Each delivery carries three headers: ``` svix-id: msg_2gT8sV... # unique message id (the body's event_id, prefixed msg_) svix-timestamp: 1718960400 # unix seconds when the delivery was signed svix-signature: v1,g0hM9SsE... # space-separated list of v1, ``` Your signing secret (prefixed `whsec_`) is returned in plaintext **exactly once** — when you create a webhook endpoint or rotate its secret. Store it securely; you cannot retrieve it again. **Verify with a Svix library (recommended):** ```python from svix.webhooks import Webhook wh = Webhook(signing_secret) # the whsec_... value payload = wh.verify(raw_request_body, request_headers) # raises on a bad signature ``` **Verify manually:** 1. Build the signed content by joining the id, timestamp, and the **raw** request body with dots: ``` signed_content = svix_id + "." + svix_timestamp + "." + raw_body ``` 2. Take your signing secret, drop the `whsec_` prefix, and base64-decode the remainder — those bytes are your HMAC key. 3. Compute `base64(HMAC-SHA256(key, signed_content))`. 4. The `svix-signature` header is a space-separated list of `v1,` entries (an endpoint can have more than one valid secret during a rotation). Compare your computed value against each entry's signature — the part after `v1,` — using a constant-time comparison, and accept if any matches. 5. Reject deliveries whose `svix-timestamp` differs from your current time by more than a few minutes, to guard against replay. The body's `event_id` equals the `svix-id` without its `msg_` prefix, so you can use either to deduplicate redelivered events. ## Request IDs Every response carries an `X-Request-Id` header (also surfaced in `meta.request_id`). Include the value when reporting issues — it scopes backend logs to your specific request. You may also send your own `X-Request-Id` header. Values matching `^[A-Za-z0-9_-]{1,128}$` are honored verbatim; anything else is replaced with a generated id. ## Versioning Public endpoints are versioned under `/v1/`. Breaking changes ship under a new major version; additive changes (new fields, new endpoints) ship under the existing version. contact: name: Paystack Cross-Border url: https://globalstack.io servers: - url: https://api.globalstack.io description: Production security: - BearerAuth: [] tags: - name: Supported Countries - name: Supported Currencies - name: Customers - name: Wallets - name: Beneficiaries - name: Quotes - name: Onramps - name: Offramps - name: Conversions - name: Transfers - name: Transactions - name: Notification Webhooks - name: Me paths: /v1/currencies/: get: tags: - Supported Currencies summary: List currencies description: > List supported currencies with networks, directional transaction limits (inbound / outbound), capability flags (`can_onramp`, `can_offramp`, `can_deposit`, `can_convert`), and current conversion fees (`fees`) keyed by settlement network. Flag meaning depends on `type` — see the API overview. Each `fees.payment_methods` entry describes the tiered fee ladder and per-chain network fees for its settlement network, split by `offramp` / `onramp` when both directions are supported. `fees` is `null` for crypto currencies and when fee data is unavailable. Each row is unique by `code` plus `country_code` (for example every WAEMU country has its own `XOF` entry with its own networks and limits). Use filters to find currencies that support a given operation or network, then paginate with `page` and `per_page`. For which countries and networks we cover, start with `GET /v1/countries`. For banks and mobile money operators (`provider_id` on fiat beneficiaries), use `GET /v1/countries/{country_code}/providers` — not this resource. ### Platform view vs customer view Without `customer_id`, the capability flags answer "can this be done on the platform" — they are the same for every caller. Pass the optional `customer_id` query parameter (a customer id, `cust_…`) and the same flags answer a narrower question: can **this customer** do this right now? Capabilities that depend on the customer's state are downgraded — today, fiat `can_deposit` reads `false` when the customer's KYC is not approved. The capability filters (`can_deposit=true`, …) are then evaluated against the customer's view too, so a filtered listing never advertises an operation the customer would be blocked from. Every downgraded row carries a `customer_restrictions` array explaining the downgrade. Each entry has: - `capability` — the capability that was removed (e.g. `deposit`). - `reason` — a stable machine code (e.g. `customer_kyc_not_approved`). - `next_steps` — `{ action, docs_url }` with what to do about it. `customer_restrictions` entries are the exact diff between the platform view and the customer view: they appear **only** for capabilities the platform supports (`true` at platform level) that the customer's state removes. A capability that is `false` at platform level is never annotated, and the field is omitted entirely on rows with no downgrade and in the platform view. An unknown `customer_id`, or one belonging to another integration, returns 404 `not_found`; a malformed one returns 400 `invalid_input`. See the full [customer restrictions reference](https://docs.globalstack.io/api-reference/customer-restrictions) for all restriction reasons. ### Filter behavior - `code` — filter by ISO currency code (e.g. `XOF` returns all WAEMU country rows). - `type` — `fiat` or `crypto`. - `country_code` — filter by ISO 3166-1 alpha-2 country code. - `customer_id` — customer id (`cust_…`). Switches the listing to that customer's view (see above). - `can_onramp` — boolean. Currencies that can participate in onramps. For fiat, usable as onramp source; for crypto, as onramp destination. - `can_offramp` — boolean. Currencies that can participate in offramps. For fiat, usable as offramp destination; for crypto, as offramp source. - `can_deposit` — boolean. Currencies that can participate in deposits (typically crypto only). - `can_convert` — boolean. Currencies that participate in wallet-to-wallet conversions. - `network` — only currencies that include this network in their `networks` array. - `min_inbound_amount` — decimal string. Only currencies where at least one network has inbound min less than or equal to this value. - `max_inbound_amount` — decimal string. Only currencies where at least one network has inbound max greater than or equal to this value. - `min_outbound_amount` — decimal string. Only currencies where at least one network has outbound min less than or equal to this value. - `max_outbound_amount` — decimal string. Only currencies where at least one network has outbound max greater than or equal to this value. - `page` — integer, 1-indexed page number. - `per_page` — integer page size (max 200). ### Example ``` GET /v1/currencies?type=fiat&can_offramp=true ``` operationId: CurrencyController.list parameters: - in: query name: code required: false schema: type: string - in: query name: country_code required: false schema: type: string - in: query name: type required: false schema: type: string - in: query name: customer_id required: false schema: type: string - in: query name: can_onramp required: false schema: type: string - in: query name: can_offramp required: false schema: type: string - in: query name: can_transfer required: false schema: type: string - in: query name: can_deposit required: false schema: type: string - in: query name: can_convert required: false schema: type: string responses: '200': content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiSuccessEnvelope' - type: object required: - data - meta properties: message: type: string example: Supported currencies fetched successfully data: type: array items: $ref: '#/components/schemas/CurrencyResponse' meta: $ref: '#/components/schemas/ApiResponseMetaSchema' description: Supported currencies fetched successfully '400': description: One of the boolean/enum filters or customer_id failed validation content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiErrorEnvelope' - type: object properties: code: type: string enum: - invalid_input '401': description: Unauthorized — invalid or missing API key content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiErrorEnvelope' - type: object properties: code: type: string enum: - authentication_failed '404': description: customer_id does not match a customer in this integration content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiErrorEnvelope' - type: object properties: code: type: string enum: - not_found components: schemas: ApiSuccessEnvelope: properties: status: type: boolean enum: - true example: true message: type: string description: Human-readable summary example: Resource fetched successfully code: type: string enum: - ok example: ok type: object required: - status - message - code CurrencyResponse: properties: code: type: string description: ISO 4217 currency code or token symbol example: NGN name: type: string description: Human-readable currency name example: Nigerian Naira type: enum: - fiat - crypto type: string description: Currency classification (fiat or crypto) example: fiat precision: type: integer description: Number of decimal places used when transacting in this currency example: 2 country_code: type: string description: ISO 3166-1 alpha-2 country code (null for cryptocurrencies) example: NG can_onramp: type: boolean can_offramp: type: boolean can_transfer: type: boolean can_deposit: type: boolean can_convert: type: boolean requires_access: type: boolean description: >- True when this currency is gated behind per-merchant access. Merchants without an active grant must request access via POST /v1/currencies/:code/access-requests before use. example: false has_access: type: boolean description: >- True iff `requires_access` is false OR the caller holds an active grant for this currency. Omitted when the caller has no merchant context. example: true networks: items: $ref: '#/components/schemas/CurrencyNetworkResponse' type: array fees: $ref: '#/components/schemas/CurrencyFeesResponse' description: >- Conversion fees for this currency, keyed by payment method (settlement network). null when the caller is unauthenticated pre-KYC, when the currency has no published fees (e.g. crypto), or when fee lookup upstream failed. nullable: true customer_restrictions: items: $ref: '#/components/schemas/CustomerRestrictionResponse' type: array description: >- Present only when customer_id was provided AND this customer's state removes a capability the platform otherwise supports. Each entry is one downgraded capability with a machine reason and next steps — the exact diff between the platform view and this customer's view. Capabilities the platform itself does not support are never listed here. created_at: type: string format: date-time example: '2025-01-15T12:34:56.000Z' updated_at: type: string format: date-time example: '2025-01-15T12:34:56.000Z' type: object required: - code - name - type - precision - can_onramp - can_offramp - can_transfer - can_deposit - can_convert - requires_access - networks - created_at - updated_at ApiResponseMetaSchema: properties: request_id: type: string description: ULID-prefixed identifier for this request example: req_01HXYZ4K5ABCDEFGHJKLMNPQRS timestamp: type: string format: date-time example: '2026-05-14T15:43:55.732Z' version: type: string description: Major API version parsed from /vN/ example: '1' type: object required: - request_id - timestamp - version ApiErrorEnvelope: properties: status: type: boolean enum: - false example: false message: type: string description: Human-readable failure summary example: Resource not found code: type: string description: Stable error code for branching logic example: not_found data: type: object nullable: true example: null meta: $ref: '#/components/schemas/ApiErrorMetaSchema' type: object required: - status - message - code - data - meta CurrencyNetworkResponse: properties: network: enum: - mobile_money - bank - solana - base - ethereum type: string description: Settlement network supported by this currency example: bank inbound: $ref: '#/components/schemas/NetworkRangeResponse' outbound: $ref: '#/components/schemas/NetworkRangeResponse' type: object required: - network - inbound - outbound CurrencyFeesResponse: properties: payment_methods: items: $ref: '#/components/schemas/PaymentMethodFeesResponse' type: array type: object required: - payment_methods CustomerRestrictionResponse: properties: capability: enum: - deposit type: string description: The capability removed for this customer example: deposit reason: enum: - customer_kyc_not_approved type: string description: Stable machine reason for the restriction example: customer_kyc_not_approved next_steps: $ref: '#/components/schemas/CustomerRestrictionNextStepsResponse' type: object required: - capability - reason - next_steps ApiErrorMetaSchema: properties: next_steps: $ref: '#/components/schemas/NextStepsSchema' request_id: type: string description: ULID-prefixed identifier for this request example: req_01HXYZ4K5ABCDEFGHJKLMNPQRS timestamp: type: string format: date-time example: '2026-05-14T15:43:55.732Z' version: type: string description: Major API version parsed from /vN/ example: '1' type: object required: - next_steps - request_id - timestamp - version NetworkRangeResponse: properties: min: type: string description: Minimum amount supported, as a decimal string example: '1.00' max: type: string description: Maximum amount supported, as a decimal string example: '5000000.00' type: object required: - min - max PaymentMethodFeesResponse: properties: network: enum: - mobile_money - bank - solana - base - ethereum type: string description: Settlement network these fees apply to. example: bank offramp: $ref: '#/components/schemas/FeeScheduleResponse' onramp: $ref: '#/components/schemas/FeeScheduleResponse' type: object required: - network CustomerRestrictionNextStepsResponse: properties: action: type: string description: What to do to lift the restriction docs_url: type: string description: Documentation link for the restriction type: object required: - action - docs_url NextStepsSchema: properties: action: type: string description: Suggested action for the caller example: Verify the resource identifier and retry. docs_url: type: string format: uri example: https://docs.globalstack.io/errors#not_found type: object required: - action - docs_url FeeScheduleResponse: properties: tiers: items: $ref: '#/components/schemas/FeeTierResponse' type: array network_fees: $ref: '#/components/schemas/FeeNetworkFeesResponse' type: object required: - tiers - network_fees FeeTierResponse: properties: transaction_value_min: type: number description: >- Inclusive lower bound of the tier in the currency's minor units, or null when unbounded below. example: 4001 transaction_value_max: type: number description: >- Inclusive upper bound of the tier in the currency's minor units, or null when unbounded above. example: 22000 fee_type: type: string enum: - percentage - flat example: percentage fee_value: type: number description: >- Fee value — a percentage when fee_type is percentage, otherwise a flat amount in the currency's minor units. example: 1.5 min_fee: type: number description: Minimum fee floor (currency minor units), or null when unbounded. example: 60 max_fee: type: number description: Maximum fee cap (currency minor units), or null when uncapped. example: 330 type: object required: - fee_type - fee_value FeeNetworkFeesResponse: properties: ethereum: type: number base: type: number solana: type: number type: object required: - ethereum - base - solana securitySchemes: BearerAuth: type: http scheme: bearer description: API key issued during merchant onboarding. ````