> ## Documentation Index
> Fetch the complete documentation index at: https://docs.countrystatecity.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Currency by Country

> Retrieve the official currency for a single country by ISO2, ISO3, or numeric ID

Retrieve the currency used by a single country. The path parameter accepts **three forms** for flexibility:

* ISO 3166-1 alpha-2 code (e.g., `US`, `IN`)
* ISO 3166-1 alpha-3 code (e.g., `USA`, `IND`)
* Numeric country ID (e.g., `233` for the United States in our database)

<Note>**Availability:** Starter plan and above. Returns `403` on lower tiers.</Note>

<Info>Responses are cached server-side for 24 hours. Equivalent identifier forms (e.g., `1` and `001`) resolve to the same cache slot.</Info>

<RequestExample>
  ```bash cURL (ISO2) theme={null}
  curl -X GET 'https://api.countrystatecity.in/v1/currency/US' \
    -H 'X-CSCAPI-KEY: YOUR_API_KEY'
  ```

  ```bash cURL (ISO3) theme={null}
  curl -X GET 'https://api.countrystatecity.in/v1/currency/IND' \
    -H 'X-CSCAPI-KEY: YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.countrystatecity.in/v1/currency/US', {
    headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
  });

  const { currency } = await response.json();
  console.log(`${currency.symbol} ${currency.code}`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
    'https://api.countrystatecity.in/v1/currency/US',
    headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
  )

  data = response.json()
  print(f"{data['country']} uses {data['currency']['code']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "country": "US",
    "currency": {
      "code": "USD",
      "name": "United States dollar",
      "symbol": "$"
    }
  }
  ```

  ```json 200 - Edge case (symbol null) theme={null}
  {
    "country": "CU",
    "currency": {
      "code": "CUP",
      "name": "Cuban peso",
      "symbol": null
    }
  }
  ```

  ```json 403 - Feature Restricted theme={null}
  {
    "status": "error",
    "message": "This feature is not available on your current plan.",
    "details": {
      "feature": "currencyApi",
      "currentTier": "community",
      "requiredTier": "starter",
      "upgradeUrl": "https://app.countrystatecity.in/pricing"
    }
  }
  ```

  ```json 404 - Country Not Found theme={null}
  {
    "error": "Country not found."
  }
  ```

  ```json 404 - No Currency Data theme={null}
  {
    "error": "No currency data available for this country."
  }
  ```
</ResponseExample>

## Related Endpoints

* [List All Currencies](/api/endpoints/list-all-currencies) — every country's currency in one call, with optional reverse lookup
* [Get Country Details](/api/endpoints/get-country-details) — full country record including currency fields inline


## OpenAPI

````yaml GET /currency/{ciso}
openapi: 3.0.3
info:
  title: Country State City API
  description: >-
    Geographic data API providing countries, states, cities, timezones,
    currencies, and phone dial codes with tiered access levels.


    ## Authentication

    All endpoints require an API key passed via the `X-CSCAPI-KEY` header. Get
    your free key at [app.countrystatecity.in](https://app.countrystatecity.in).


    ## Pricing & Limits

    The fields returned, endpoints available, and request quotas depend on your
    plan. See current tiers and limits at:


    **[countrystatecity.in/pricing](https://countrystatecity.in/pricing)**


    ## Data Access Levels

    Each plan includes a data access level that controls which fields are
    returned:


    - **Basic** — Core fields: id, name, iso2, iso3, phonecode, capital,
    currency, coordinates, region, timezones, emoji

    - **Coordinates** — Basic + extended metadata (population, tld, nationality,
    currency details, postal codes, etc.)

    - **Full** — All fields including translations (18+ languages) and
    wikiDataId


    Fields restricted to higher tiers are marked in each schema below.


    ## Feature Gating

    Some endpoints require a minimum tier. Restricted endpoints return `403`
    with an `upgradeUrl` when accessed on a lower plan. Check the [pricing
    page](https://countrystatecity.in/pricing) for current feature availability.


    ## Rate Limiting

    Requests exceeding your daily or monthly quota receive a `429` response with
    your current limit, period, tier, and an upgrade URL.


    ## Caching

    Cacheable geographic responses include `Cache-Control`, `ETag`, and
    `X-Cache` (HIT/MISS) headers; send `If-None-Match` on them to receive `304
    Not Modified`. Phone number parsing is never cached (`Cache-Control:
    no-store`, no `ETag`); see each endpoint for exceptions.


    ## Usage Headers

    All `/v1/*` responses include usage and plan headers:

    - `X-CSC-Plan` — your current tier

    - `X-CSC-Daily-Used` / `X-CSC-Daily-Limit` — today's usage vs limit

    - `X-CSC-Monthly-Used` / `X-CSC-Monthly-Limit` — this month's usage vs limit


    Use these to monitor consumption without a separate API call.
  contact:
    name: Darshan Gada (dr5hn)
    email: gadadarshan@gmail.com
    url: https://countrystatecity.in
  license:
    name: Creative Commons Attribution 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  version: 2.4.1
servers:
  - url: https://api.countrystatecity.in/v1
    description: Production API
security: []
tags:
  - name: Countries
    description: Country data — 250+ countries with metadata, coordinates, and translations
  - name: States
    description: State/province/region data — 5,000+ subdivisions
  - name: Cities
    description: City data — 150,000+ cities worldwide
  - name: Postcodes
    description: >-
      Postcode and ZIP code lookup and search. Informational data, not address
      verification.
  - name: Regions
    description: Geographic regions and subregions — continental groupings of countries
  - name: Timezones
    description: >-
      IANA timezone lookup by country, state, or city — includes UTC offset and
      DST status
  - name: Currencies
    description: ISO 4217 currency data — list all currencies or look up by country
  - name: Phone
    description: >-
      International dial codes — list, lookup by country, and E.164 phone number
      parsing
  - name: ISO
    description: >-
      ISO 3166 code lookup and conversion — country (alpha-2/3/numeric) and
      state (ISO 3166-2)
  - name: Search
    description: Typo-tolerant fuzzy search across cities, states, and countries
  - name: Changes
    description: >-
      Data change feed — track additions, removals, and updates to place records
      over time. **Professional and Business plans only.**
  - name: Meta
    description: Information about the dataset release currently served
paths:
  /currency/{ciso}:
    get:
      tags:
        - Currencies
      summary: Get currency by country
      description: >-
        Returns the official ISO 4217 currency for a single country.


        **Availability:** Starter+ plan required. Responses cached server-side
        for 24 hours.
      operationId: getCurrencyByCountry
      parameters:
        - name: ciso
          in: path
          description: >-
            ISO 3166-1 alpha-2 (e.g., `IN`), alpha-3 (e.g., `IND`), or numeric
            country ID (e.g., `101`)
          required: true
          schema:
            type: string
            example: IN
      responses:
        '200':
          description: Currency data for the country
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
            ETag:
              $ref: '#/components/headers/ETag'
            X-Cache:
              $ref: '#/components/headers/XCache'
            X-CSC-Plan:
              $ref: '#/components/headers/XCSCPlan'
            X-CSC-Daily-Used:
              $ref: '#/components/headers/XCSCDailyUsed'
            X-CSC-Daily-Limit:
              $ref: '#/components/headers/XCSCDailyLimit'
            X-CSC-Monthly-Used:
              $ref: '#/components/headers/XCSCMonthlyUsed'
            X-CSC-Monthly-Limit:
              $ref: '#/components/headers/XCSCMonthlyLimit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrencyInfo'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/FeatureRestricted'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - ApiKeyAuth: []
components:
  headers:
    CacheControl:
      description: Cache directive
      schema:
        type: string
        example: public, max-age=3600
    ETag:
      description: Entity tag for conditional requests (use with `If-None-Match`)
      schema:
        type: string
        example: '"a3f2b8c1d4e5f6a7b8c9d0e1f2a3b4c5"'
    XCache:
      description: Whether the response was served from cache
      schema:
        type: string
        enum:
          - HIT
          - MISS
        example: HIT
    XCSCPlan:
      description: Your current pricing tier
      schema:
        type: string
        enum:
          - community
          - starter
          - supporter
          - professional
          - business
          - legacy
          - custom
        example: supporter
    XCSCDailyUsed:
      description: Number of requests used today
      schema:
        type: integer
        example: 42
    XCSCDailyLimit:
      description: Your daily request limit (or 'unlimited' for custom plans)
      schema:
        type: string
        example: '1000'
    XCSCMonthlyUsed:
      description: Number of requests used this month
      schema:
        type: integer
        example: 850
    XCSCMonthlyLimit:
      description: Your monthly request limit (or 'unlimited' for custom plans)
      schema:
        type: string
        example: '30000'
  schemas:
    CurrencyInfo:
      type: object
      description: >-
        Currency data for a country. `currency.name` and `currency.symbol` may
        be null for a small number of entries.
      properties:
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: IN
        currency:
          type: object
          properties:
            code:
              type: string
              description: ISO 4217 currency code — always present
              example: INR
            name:
              type: string
              nullable: true
              description: Full currency name
              example: Indian rupee
            symbol:
              type: string
              nullable: true
              description: Unicode currency symbol; fall back to `code` if null
              example: ₹
          required:
            - code
      required:
        - country
        - currency
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      required:
        - error
    FeatureError:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        message:
          type: string
          example: This feature is not available on your current plan.
        details:
          type: object
          properties:
            feature:
              type: string
              description: The feature flag that was denied
              example: bulkStates
            currentTier:
              type: string
              example: community
            requiredTier:
              type: string
              nullable: true
              description: >-
                Lowest plan that unlocks the feature; null when it cannot be
                determined
              example: starter
            upgradeUrl:
              type: string
              format: uri
              example: https://countrystatecity.in/pricing
          required:
            - feature
            - currentTier
            - requiredTier
            - upgradeUrl
      required:
        - status
        - message
        - details
    RateLimitError:
      type: object
      properties:
        error:
          type: string
          example: >-
            Daily usage limit exceeded. Please try again tomorrow or contact
            support for higher limits.
        limit:
          type: integer
          description: Your plan's limit for the exceeded period
          example: 100
        period:
          type: string
          enum:
            - daily
            - monthly
          example: daily
        tier:
          type: string
          description: Your current tier
          example: community
        upgradeUrl:
          type: string
          description: URL to upgrade your plan
          example: https://countrystatecity.in/pricing
      required:
        - error
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized. You shouldn't be here.
    FeatureRestricted:
      description: >-
        Feature not available on your current plan. Upgrade to access this
        endpoint. `details.feature` names the denied feature and
        `details.requiredTier` the lowest plan that includes it (the example is
        for `/states`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FeatureError'
          example:
            status: error
            message: This feature is not available on your current plan.
            details:
              feature: bulkStates
              currentTier: community
              requiredTier: starter
              upgradeUrl: https://countrystatecity.in/pricing
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Country not found.
    RateLimited:
      description: Daily or monthly usage limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            error: >-
              Daily usage limit exceeded. Please try again tomorrow or contact
              support for higher limits.
            limit: 100
            period: daily
            tier: community
            upgradeUrl: https://countrystatecity.in/pricing
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: >-
        API key for authentication. Get your free key at
        [app.countrystatecity.in](https://app.countrystatecity.in).
      name: X-CSCAPI-KEY
      in: header

````

## Related topics

- [List All Currencies](/api/endpoints/list-all-currencies.md)
- [Errors & Rate Limits](/api/errors.md)
- [Get All Countries](/api/endpoints/get-all-countries.md)
- [Get Country Details](/api/endpoints/get-country-details.md)
- [Get Countries by Subregion](/api/endpoints/get-countries-by-subregion.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.