Price API Reference

Complete reference for the Price API endpoints. Fetch token prices, currencies, currency exchange rates, and fiat quotes.

Base URL

https://api.orcarail.com/api/v1

Token Price

Get Token Price

Get the latest USD price for a token by token ID.

GET /price/token/:tokenId

Path Parameters

Parameter	Type	Required	Description
tokenId	string	Yes	Token ID (UUID)

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tokenId": "550e8400-e29b-41d4-a716-446655440001",
  "priceUsd": "2500.00",
  "source": "coingecko",
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Returns null if no price is available for the token.

Response Fields

Field	Type	Description
id	string	Price record ID (UUID)
tokenId	string	Token ID (UUID)
priceUsd	string	Price in USD
source	string	Price source (e.g., coingecko, manual)
createdAt	string	ISO 8601 timestamp

Currencies

List Currencies

List supported fiat/display currencies.

GET /price/currencies

Query Parameters

Parameter	Type	Required	Description
active	string	No	Set to true to return only active currencies

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "USD",
    "name": "US Dollar",
    "symbol": "$",
    "decimals": 2,
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
]

Currency Rate

Get Currency Rate

Get the latest exchange rate between two currencies (base and quote).

GET /price/currency-rate/:baseId/:quoteId

Path Parameters

Parameter	Type	Required	Description
baseId	string	Yes	Base currency ID (UUID)
quoteId	string	Yes	Quote currency ID (UUID)

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "baseCurrencyId": "550e8400-e29b-41d4-a716-446655440001",
  "quoteCurrencyId": "550e8400-e29b-41d4-a716-446655440002",
  "rate": "590000.00",
  "source": "manual",
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Returns null if no rate is available for the pair.

Response Fields

Field	Type	Description
id	string	Rate record ID (UUID)
baseCurrencyId	string	Base currency ID (UUID)
quoteCurrencyId	string	Quote currency ID (UUID)
rate	string	Exchange rate (1 base = rate quote)
source	string	Rate source (e.g., manual)
createdAt	string	ISO 8601 timestamp

Fiat Quote

Get Fiat Quote

Get a fiat-to-USD/USDC quote. Optionally get the equivalent amount in a specific token.

GET /price/fiat-quote

Query Parameters

Parameter	Type	Required	Description
amount	string	Yes	Amount in source currency (e.g., 100000)
currency	string	Yes	Source currency code (e.g., irr, usd)
tokenId	string	No	Token ID (UUID) to get amount in that token

Response

{
  "amountUsd": "2.38",
  "amountUsdc": "2.38",
  "sourceAmount": "100000",
  "sourceCurrency": "irr",
  "currencyRateId": "550e8400-e29b-41d4-a716-446655440000",
  "tokenAmount": "0.00052",
  "tokenSymbol": "ETH"
}

When tokenId is not provided, tokenAmount and tokenSymbol are omitted. When the source currency is USD, currencyRateId may be null.

Response Fields

Field	Type	Description
amountUsd	string	Amount in USD
amountUsdc	string	Amount in USDC (same as USD for stablecoin)
sourceAmount	string	Original amount in source currency
sourceCurrency	string	Source currency code
currencyRateId	string | null	Currency rate ID used for conversion (null when USD)
tokenAmount	string	Optional. Amount in selected token (when tokenId given)
tokenSymbol	string	Optional. Symbol of selected token (when tokenId given)

Status Codes

Status Code	Description
200	Success
404	Not Found (e.g., no price or rate for the given IDs)
500	Internal Server Error

See Also

• Payments - Networks and tokens (for token IDs)
• Dashboard - Balances and volumes
• Node SDK API Reference - orcarail.rates.getFiatQuote and getCurrencies
• Demo - Currency selector and fiat quote usage