solution: api for requesting the historical market prices

Author: splix

api-definitions

@@ -80,15 +80,16 @@ export {
 } from './typesCommon';
 export { MessageFactory } from './typesConvert';
 export {
+  CryptoCurrency,
+  StablecoinCurrency,
+  CountryCurrency,
+  BaseCurrency,
   AnyCurrency,
   ConvertMarket,
-  CountryCurrency,
-  CryptoCurrency,
   GetRatesRequest,
   GetRatesResponse,
   Pair,
   Rate,
-  StablecoinCurrency,
   TestCurrency,
 } from './typesMarket';
 export * as token from './typesToken';

packages/core/src/index.ts

@@ -1,10 +1,11 @@
 import * as market_pb from './generated/market_pb';
+import * as common_pb from './generated/common_pb';
 import { DataMapper } from './Publisher';
-import { ConvertCommon, Erc20Asset, isErc20Asset } from './typesCommon';
+import { Blockchain, ConvertCommon, Erc20Asset, isErc20Asset } from './typesCommon';
 import { MessageFactory } from './typesConvert';
 
-export type CryptoCurrency = 'BTC' | 'GRIN' | 'ETC' | 'ETH';
-export type StablecoinCurrency = 'DAI' | 'SAI' | 'USDT';
+export type CryptoCurrency = 'BTC' | 'ETC' | 'ETH';
+export type StablecoinCurrency = 'DAI' | 'USDT' | 'USDC';
 export type CountryCurrency =
   | 'USD'
   | 'EUR'
@@ -20,29 +21,95 @@ export type CountryCurrency =
   | 'KRW'
   | 'SGD'
   | 'INR';
-export type TestCurrency = 'MONOPOLY' | 'KOVAN' | 'TEST_BTC';
+export type TestCurrency = 'MONOPOLY' | 'KOVAN' | 'TEST_BTC' | 'TEST_BTC_V4' | 'SEPOLIA';
 
 export type BaseCurrency = CryptoCurrency | StablecoinCurrency | CountryCurrency | TestCurrency;
 export type AnyCurrency = BaseCurrency | Erc20Asset;
 
-export type GetRatesRequest = Pair[];
 
+/**
+ * Currency pair
+ */
 export type Pair = {
   base: AnyCurrency;
   target: AnyCurrency;
 };
 
-export type GetRatesResponse = Rate[];
+/**
+ * Request the rate at specified moment.
+ */
+export type GetRatesRequestAt = {
+  // Request the rate at the specified moment.
+  timestamp: number | Date;
+  // The rates
+  pairs: Pair[];
+}
+
+/**
+ * Request the rate at the moment of the specified block.
+ */
+export type GetRatesRequestByBlock = {
+  // Request the rate at the moment of the specified block.
+  block: BlockRefAtHeight | BlockRefAtHash;
+  // The rates
+  pairs: Pair[];
+}
+
+/**
+ * Reference to a block by its height.
+ */
+export type BlockRefAtHeight = {
+  // The blockchain to which the block belongs.
+  blockchain: Blockchain,
+  // The height of the block.
+  height: number,
+}
+
+/**
+ * Reference to a block by its hash.
+ */
+export type BlockRefAtHash = {
+  // The blockchain to which the block belongs.
+  blockchain: Blockchain,
+  // The hash of the block.
+  hash: string
+}
+
+/**
+ * Request the latest available rate.
+ * Note, there rates are averaged from multiple exchanges and it always a slight delay to fetch the trades.
+ * Because of that, when requesting the latest rate, it may fluctuate a little between the requests.
+ */
+export type GetRatesRequestLatest = Pair[] | { pairs: Pair[] }
+
+/**
+ * Reqeust the rates. It can be either the latest available rates, or the rates at the specified moment (timestamp or block).
+ */
+export type GetRatesRequest = GetRatesRequestLatest | GetRatesRequestAt | GetRatesRequestByBlock;
+
 
+/**
+ * Currency pair with the exchange rate.
+ */
 export type Rate = {
   base: AnyCurrency;
   target: AnyCurrency;
   /**
    * exchange rate decimal encoded as a string
    */
   rate: string;
+
+  /**
+   * Timestamp of the moment when the rate was established.
+   * It points to the moment when the last time one of the components of the pair was traded, which affected the rate.
+   * It's assumed that if there were no trades between that moment, and the moment of the request then the rate is still valid.
+   * I.e., it's the last known evidence of the rate. If multiple pairs requested, the timestamp of each pair may be different.
+   */
+  timestamp?: Date;
 };
 
+export type GetRatesResponse = Rate[];
+
 export class ConvertMarket {
   private readonly factory: MessageFactory;
 
@@ -53,10 +120,22 @@ export class ConvertMarket {
     this.common = common;
   }
 
-  public ratesRequest(pairs: GetRatesRequest): market_pb.GetRatesRequest {
+  /**
+   * Convert TypeScript type to Protobuf message
+   * @param request
+   */
+  public ratesRequest(request: GetRatesRequest): market_pb.GetRatesRequest {
     const req: market_pb.GetRatesRequest = this.factory('market_pb.GetRatesRequest');
 
-    pairs.forEach((pair) => {
+    let pairsList: Pair[];
+
+    if (Array.isArray(request)) {
+        pairsList = request;
+    } else if ('pairs' in request) {
+        pairsList = request.pairs;
+    }
+
+    pairsList.forEach((pair) => {
       const pairProto: market_pb.Pair = this.factory('market_pb.Pair');
 
       if (isErc20Asset(pair.base)) {
@@ -73,9 +152,27 @@ export class ConvertMarket {
 
       req.addPairs(pairProto);
     });
+
+    if ('timestamp' in request) {
+      req.setTimestamp(request.timestamp instanceof Date ? request.timestamp.getTime() : request.timestamp);
+    } else if ('block' in request) {
+      const blockRef = request.block;
+      const blockRefProto: common_pb.BlockRef = this.factory('common_pb.BlockRef');
+      blockRefProto.setBlockchain(blockRef.blockchain.valueOf());
+      if ('height' in blockRef) {
+        blockRefProto.setHeight(blockRef.height);
+      } else if ('hash' in blockRef) {
+        blockRefProto.setBlockId(blockRef.hash);
+      }
+      req.setBlock(blockRefProto);
+    }
+
     return req;
   }
 
+  /**
+   * Convert Protobuf message to TypeScript type
+   */
   public ratesResponse(): DataMapper<market_pb.GetRatesResponse, GetRatesResponse> {
     return (value) => {
       const rates: Rate[] = value.getRatesList().map((rate) => {
@@ -89,19 +186,25 @@ export class ConvertMarket {
           throw new Error('No base currency in rate');
         }
 
-        let target;
+        let target: AnyCurrency;
 
         if (rate.hasErc20Target()) {
           target = this.common.erc20Asset(rate.getErc20Target());
         } else if (rate.hasTarget()) {
-          target = rate.getTarget();
+          target = rate.getTarget() as BaseCurrency;
+        }
+
+        let timestamp: Date | undefined = undefined;
+        if (rate.getTimestamp() > 0) {
+          timestamp = new Date(rate.getTimestamp());
         }
 
         return {
           base: base,
           target: target,
           rate: rate.getRate(),
-        } as Rate;
+          timestamp: timestamp,
+        }
       });
 
       return rates;

packages/core/src/typesMarket.ts

@@ -61,6 +61,8 @@ export const classFactory: MessageFactory = (id: string) => {
       return new market_pb.GetRatesRequest();
     case 'market_pb.Pair':
       return new market_pb.Pair();
+    case 'common_pb.BlockRef':
+      return new common_pb.BlockRef();
     // Token
     case 'token_message_pb.AddressAllowanceRequest':
       return new token_message_pb.AddressAllowanceRequest();

packages/node/src/wrapped/Factory.ts

@@ -1,4 +1,5 @@
-import {EmeraldApi} from "../EmeraldApi";
+import { EmeraldApi } from "../EmeraldApi";
+import { Blockchain } from "@emeraldpay/api";
 
 jest.setTimeout(5000);
 
@@ -21,6 +22,41 @@ describe("MarketClient", () => {
         expect(parseFloat(act[0].rate)).toBeGreaterThan(50);
     });
 
+    test('Get ETH rate at block 24319623', async () => {
+        const client = api.market;
+
+        let act = await client.getRates({
+            block: {
+                blockchain: Blockchain.ETHEREUM,
+                height: 24319623,
+            },
+            pairs: [{base: "ETH", target: "USD"}],
+        });
+        console.log("rates", act);
+
+        expect(act.length).toBe(1);
+        expect(act[0].base).toBe("ETH");
+        expect(act[0].target).toBe("USD");
+        expect(parseFloat(act[0].rate)).toBeGreaterThan(2850.0);
+        expect(parseFloat(act[0].rate)).toBeLessThan(2950.0);
+    });
+
+    test('Get ETH rate at 6 Feb 2026', async () => {
+        const client = api.market;
+
+        let act = await client.getRates({
+            timestamp: new Date('2026-02-06T12:00:00Z'),
+            pairs: [{base: "ETH", target: "USD"}],
+        });
+        console.log("rates", act);
+
+        expect(act.length).toBe(1);
+        expect(act[0].base).toBe("ETH");
+        expect(act[0].target).toBe("USD");
+        expect(parseFloat(act[0].rate)).toBeGreaterThan(1900.0);
+        expect(parseFloat(act[0].rate)).toBeLessThan(2000.0);
+    });
+
     test('Get BTC rate', async () => {
         const client = api.market;
 

packages/web/src/__integration-tests__/market.test.ts

@@ -75,6 +75,10 @@ export const classFactory: MessageFactory = (id: string) => {
     if (id == "market_pb.Pair") {
         return new market_pb.Pair();
     }
+    if (id == "common_pb.BlockRef") {
+        return new common_pb.BlockRef();
+    }
+
     // Sierra
     if (id == "sierra_message_pb.CreateProjectRequest") {
         return new sierra_message_pb.CreateProjectRequest();