# Find a token by its on-ledger identity

Use the `issuer`, `assetCode`, and `assetReference` query parameters of the tickers API to retrieve exactly one token from the identifiers the ledger assigns to it. These filters bind to the token's immutable on-ledger identity, not to its `name` or `symbol`, which are editable and can be identical across tokens.

Why name and symbol aren't enough
Ripple Custody can track more than one ticker for what you consider one asset. On the XRP Ledger, two issuers can issue tokens with the same currency code, and an authorized trust line can register a token twice. For a currency code longer than three characters, Ripple Custody sets both `name` and `symbol` to the same 40-character hexadecimal code, so the tickers look identical in the API. Only the issuer tells them apart. The identity filters let you select the right one in a single call, without renaming tokens or filtering client-side.

## Prerequisites

Before looking up a token, you need the following:

| Prerequisite | Additional information |
|  --- | --- |
| API authentication | [Authenticate API requests](/products/custody/v1.42/identity-and-access/authentication/authenticate-api-requests) |
| Ledger ID | [List ledgers](/products/custody/v1.42/reference/api/openapi/ledgers/getledgers) |
| The token's on-ledger identifiers | From the token issuer or the ledger. See [Which parameters to use](#which-parameters-to-use). |


## Which parameters to use

The ledger determines which identifiers make a token unique. Each identity filter corresponds to a field in the ticker's `ledgerDetails.properties` object, so a ticker you already hold shows you the exact values to send.

| Ledger and token type | Parameters | Value in `ledgerDetails.properties` |
|  --- | --- | --- |
| XRPL fungible token (trust line) | `assetCode` and `issuer` | `currencyCode` and `issuer` |
| XRPL Multi-Purpose Token (MPT) | `assetReference` | `issuanceId` |
| Stellar token | `assetCode` and `issuer` | `code` and `issuer` |
| EVM ERC-20 | `assetReference` | `address` |
| EVM ERC-721 and ERC-1155 | `assetReference` as `<address>-<tokenId>` | `address` and `tokenId` |
| Solana token | `assetReference` | `mint` |
| Tron TRC-20 | `assetReference` | `contractAddress` |
| Hedera fungible token | `assetReference` | `id` |
| Hedera NFT | `assetReference` as `<id>-<serialNumber>` | `id` and `serialNumber` |


Use `assetCode` and `issuer` together for ledgers that identify a token by a code and an issuing address. Use `assetReference` alone for ledgers that identify a token by a single reference. Native assets have no on-ledger identity fields, so filter them with `kind=Native` and `ledgerId` instead.

Always combine the identity filters with `ledgerId`. The same code or reference can exist on more than one ledger, for example a Stellar asset and an XRPL token that both use the code `USD`.

## Look up an XRPL fungible token

Send the currency code and the issuing address together with the ledger ID:

```bash
curl -s -G "https://{host}/v1/tickers" \
  -H "Authorization: Bearer <jwt>" \
  --data-urlencode "ledgerId=xrpl-testnet-august-2024" \
  --data-urlencode "assetCode=USD" \
  --data-urlencode "issuer=rNYFkgmxPfLNtRjp5S4Fswka6qoVknrDFQ"
```

The response contains one item, and `count` is `1`:

```json
{
  "items": [
    {
      "id": "0bd4509b-74fd-4cb1-bb74-41cc0ff2e0b4",
      "ledgerId": "xrpl-testnet-august-2024",
      "kind": "Token",
      "name": "USD",
      "decimals": 81,
      "symbol": "USD",
      "ledgerDetails": {
        "properties": {
          "currencyCode": "USD",
          "issuer": "rNYFkgmxPfLNtRjp5S4Fswka6qoVknrDFQ",
          "type": "FungibleToken"
        },
        "type": "XRPL"
      },
      "data": { "...": "..." },
      "signature": "..."
    }
  ],
  "count": 1,
  "currentStartingAfter": null,
  "nextStartingAfter": "0bd4509b-74fd-4cb1-bb74-41cc0ff2e0b4"
}
```

For the full item shape, see [View tokens](/products/custody/v1.42/accounts-and-assets/tokenization/token-management/api/view-tokens#response-example).

When two issuers use the same currency code, `assetCode` alone returns both tickers, which is correct: the code identifies two distinct assets. Adding `issuer` narrows the result to one.

## Look up an XRPL Multi-Purpose Token

An MPT has no issuer property. Send its issuance ID as `assetReference`:

```bash
curl -s -G "https://{host}/v1/tickers" \
  -H "Authorization: Bearer <jwt>" \
  --data-urlencode "ledgerId=xrpl-testnet-august-2024" \
  --data-urlencode "assetReference=0139A521949E64726D9568F2805B4F58700BACCB4FE59E44"
```

Don't add `issuer` to an MPT lookup. Because MPTs carry no issuer, the combination matches nothing and returns zero results. For more about issuance IDs, see [Multi-purpose tokens](/products/custody/v1.42/accounts-and-assets/tokenization/xrpl-mpts#mpt-issuance-id).

## Look up an EVM token

Send the contract address as `assetReference`. For an ERC-721 or ERC-1155 token, append the token ID after a dash:

```bash
curl -s -G "https://{host}/v1/tickers" \
  -H "Authorization: Bearer <jwt>" \
  --data-urlencode "ledgerId=ethereum-mainnet" \
  --data-urlencode "assetReference=0x6b175474e89094c44da98b954eedeac495271d0f"
```

```
assetReference=0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb-7804
```

## How the filters combine

- **Filters combine with AND.** `assetCode`, `issuer`, `assetReference`, `ledgerId`, `kind`, `symbol`, and the other list parameters all narrow the same result. Contradictory filters, such as an `assetCode` and an `assetReference` that belong to different tokens, return zero results.
- **Repeated values combine with OR.** Each identity parameter is an array. `?assetCode=A&assetCode=B&issuer=X` returns tokens whose code is `A` or `B` and whose issuer is `X`.
- **Filtering happens server-side, before pagination.** A request with `limit=1` still finds a token that isn't first in the default order.
- **A wrong issuer, wrong ledger, or unknown reference returns zero results**, not an error.


## Send values exactly as the ticker stores them

The identity filters match the stored value exactly. They're case-sensitive and apply no normalization, so send the form that appears in the ticker's `ledgerDetails.properties`.

This matters most for XRPL currency codes. The XRP Ledger allows two spellings for one code, and Ripple Custody stores what the ledger reports:

| Currency code | Stored form | Example |
|  --- | --- | --- |
| Three characters | ASCII | `USD` |
| Longer than three characters | 40-character uppercase hexadecimal | `435553543334352D44454D4F0000000000000000` |


The two forms aren't interchangeable for the same asset. Against a token stored as `435553543334352D44454D4F0000000000000000`, the following all return zero results:

- The ASCII form, `CUST345-DEMO`.
- The lowercase hexadecimal form.
- The hexadecimal form of a three-character code that Ripple Custody stores as ASCII, such as `5553440000000000000000000000000000000000` for `USD`.


For the currency code formats, see [Currency codes](https://xrpl.org/docs/references/protocol/data-types/currency-formats#currency-codes) in the XRPL documentation.

## Confirm the result

Always check that `count` is `1` before you use the ticker. Two cases return a `200` response with unexpected results:

- **The API ignores a misspelled parameter name.** It doesn't reject unknown query parameters. A request with `assetRefrence=...` returns the full ticker list for the ledger, not an error.
- **A correct code that two issuers share returns two tickers** when you omit `issuer`.


An empty parameter value, such as `assetCode=`, returns a `400` error.

Treat any result other than exactly one ticker as a failed lookup. Because the value of this lookup is landing on one token, a client that accepts the first item of a multi-item response or of an unfiltered list can select the wrong token.

## Related topics

- [View tokens](/products/custody/v1.42/accounts-and-assets/tokenization/token-management/api/view-tokens)
- [Manage XRPL tokens with the API](/products/custody/v1.42/accounts-and-assets/tokenization/ledger-specific/xrpl-api)
- [Multi-purpose tokens](/products/custody/v1.42/accounts-and-assets/tokenization/xrpl-mpts)
- [API reference: List tickers](/products/custody/v1.42/reference/api/openapi/tickers/gettickers)
- [API reference: Get ticker](/products/custody/v1.42/reference/api/openapi/tickers/getticker)