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

# Instrument identifiers

> How to address a US listing, a non-US listing, a share class, and a fund.

## The short version

| What you have | What to send |
| - | - |
| A US listing | The bare symbol: `AAPL`, `NVDA`, `JPM` |
| A non-US listing | An exchange prefix: `PAR:AI`, `LON:AZN`, `TYO:7203` |
| A share class | A dash or a dot: `BRK-B` or `BRK.B` (both resolve) |
| A fund | Its ticker on [`/etfs/{symbol}`](/api-reference/etfs/get-etf), not `/instruments` |

<Warning>
  A Yahoo-style vendor suffix (`AI.PA`, `AIXA.DE`, `BESI.AS`) is **not** an
  identifier here. It resolves to nothing, because the API reads `AI.PA` as a
  US ticker literally spelled "AI.PA". Send `PAR:AI` instead. When you get this
  wrong the error names the prefixed form to use.
</Warning>

## Non-US listings

Non-US listings are addressed the way Google Finance writes them: an exchange
prefix, a colon, then the local ticker.

```bash theme={null}
curl https://api.halal.sh/v1/instruments/PAR:AI/compliance \
  -H "X-API-Key: hsh_live_your_key"
```

URL-encode the colon (`%3A`) if your HTTP client needs it. Both forms work.

The prefix names the **listing venue** when the company's home country has no
prefix of its own: a Cayman-registered company listed in Hong Kong is
`HKG:2020` (ANTA), and a Jersey company on the London Stock Exchange is
`LON:GLEN` (Glencore). When the home country has one, the identifier carries
it: China Shenhua's Hong Kong H-shares are `SHA:1088`, and `HKG:1088` reaches
the same listing. The prefixes in the second table below follow the venue:
Turkcell on Borsa Istanbul is `IST:TCELL`, while an Israeli company listed on
Nasdaq keeps its bare ticker as its `instrument_id` (`TLV:` plus that ticker
still reaches it). Every instrument and search response carries
`instrument_id`, the exact string to send, so you never have to assemble one
from `symbol` and `country_code`.

| Prefix | Exchange | Prefix | Exchange |
| - | - | - | - |
| `LON` | London | `PAR` | Euronext Paris |
| `FRA` | Frankfurt | `AMS` | Euronext Amsterdam |
| `MIL` | Borsa Italiana | `MAD` | Bolsa de Madrid |
| `BRU` | Euronext Brussels | `LIS` | Euronext Lisbon |
| `VIE` | Wiener Börse | `SWX` | SIX Swiss |
| `ISE` | Euronext Dublin | `STO` | OMX Stockholm |
| `CPH` | OMX Copenhagen | `HEL` | OMX Helsinki |
| `OSL` | Oslo Børs | `WSE` | Warsaw |
| `BDP` | Budapest | `TYO` | Tokyo |
| `KRX` | Korea | `HKG` | Hong Kong |
| `SHA` | Shanghai | `SHE` | Shenzhen |
| `TPE` | Taiwan | `SGX` | Singapore |
| `NSE` | India (NSE) | `KLS` | Bursa Malaysia |
| `JKT` | Indonesia | `BKK` | Thailand |
| `ASX` | Australia | `NZE` | New Zealand |
| `TSX` | Toronto | `BSP` | B3 (Brazil) |
| `BMV` | Mexico | `JSE` | Johannesburg |
| `TAD` | Tadawul | `ADX` | Abu Dhabi |
| `QSE` | Qatar | | |

These name the listing on that venue:

| Prefix | Exchange | Prefix | Exchange |
| - | - | - | - |
| `IST` | Borsa Istanbul | `TLV` | Tel Aviv |
| `HOSE` | Ho Chi Minh City | `PSE` | Philippines |
| `KWSE` | Boursa Kuwait | `BCS` | Santiago |
| `ATH` | Athens | `EGX` | Egypt |
| `BVC` | Colombia | `ICE` | Nasdaq Iceland |
| `MCX` | Moscow | `BVL` | Lima |
| `CAS` | Casablanca | `PRG` | Prague |
| `NGX` | Nigeria | `BVB` | Bucharest |

### Other spellings that resolve

You do not have to learn the table. The way Google Finance writes a venue
(`EPA:AI`, `EBR:UCB`, `ETR:SAP`, `BIT:ENI`, `ELI:EDP`), the venue's own name or
code (`HKEX:0669`, `LSE:AZN`, `XETRA:SAP`, `NZX:FPH`, `BME:AMS`, `TWSE:2330`,
`KOSPI:005930`, `BIST:THYAO`, `TASE:TEVA`, `MOEX:SBER`), and a US venue written as a prefix (`NASDAQ:AAPL`,
`NYSE:JPM`) all resolve to the same listing. `TSE:` is read as Tokyo when the
ticker is numeric (`TSE:7203`) and as Toronto when it is not (`TSE:SHOP`).

A Hong Kong stock code answers to any zero-padding: `HKG:992`, `HKG:0992` and
`HKG:00992` all reach Lenovo.

`POST /screen` takes the same identifiers as `/instruments`, prefixed or bare,
up to 50 per call, and echoes each one back in upper case. Dotted share classes
(`BRK.B`) resolve everywhere.

## Cross-listings and share classes

A company is analysed once, against its canonical listing. Ask for any listing
of it (an ADR, a foreign line, a second share class) and you get that company's
determination, echoed back under the symbol you asked for. So `NVO` and
`CPH:NOVO-B` return the same screens, and `BRK-B` returns Berkshire.

## Funds

Funds live on [`/etfs/{symbol}`](/api-reference/etfs/get-etf), not
`/instruments`. Around 180 fund tickers also exist as equity rows for
bookkeeping reasons, so `/instruments/SPY/compliance` answers `pending`
forever; when it does, the response carries `meta.etf` naming the endpoint that
has the real answer. [`POST /screen`](/api-reference/screening/screen) does the
same through `meta.etfs`.

The exception is a fund we screen under AAOIFI as a trust rather than by
holdings (`GLD`, `IAU`, `SLV`, `IBIT`, `USO`). Those carry a real determination
on `/instruments`, and `/etfs` has little to say about them.

A fund's alternate listing line, a same-ISIN ticker on another currency or
exchange, resolves to the fund itself.

## When an identifier does not resolve

`404 not_found` means we have no such instrument. The message names the likely
fix when there is one: the prefixed form for a vendor-suffixed ticker, or the
fund endpoint for a fund ticker. On `/screen`, unresolvable tickers come back
in `meta.not_found` rather than as fabricated rows, and the fund ones are named
in `meta.etfs`.

Use [`GET /search`](/api-reference/screening/search) when you have a name and
need the identifier: every stock hit carries `instrument_id`, the exact string
to send to `/instruments`, and every hit carries a `type` telling you whether
to route it to `/instruments` or `/etfs`.

`GET /instruments/{symbol}/health` can `404` for a listing that resolves
everywhere else. Financial health is computed from SEC filings, so a company
that does not file with the SEC has no health analysis yet; the message says
so, and the compliance determination is unaffected.