feat: Edge API integration improvements (#3534)

* feat: Edge API integration improvements

- Add statusUrl to payment-info responses (buy/sell/swap)
- Add pagination (limit/offset) to GET /transaction
- Add stateProvince parameter to quote endpoints
- Add expiryDate to payment-info responses (30 min validity)
- Add userCountry to TransactionDto
- Document amount units in Swagger and README

* fix: format

Author: davidleomay

README.md

@@ -18,6 +18,10 @@ Links to the productive API are used in the further documentation.
   - [Swagger UI](https://dev.api.dfx.swiss)
   - [Swagger JSON](https://dev.api.dfx.swiss/swagger-json)
 
+### API Conventions
+
+**Amount Representation:** All amount fields in the API use human-readable display units. For example, `1.5` means 1.5 BTC (not 150,000,000 satoshis). Crypto amounts are typically rounded to ~5 decimal places, fiat amounts to 2 decimal places.
+
 ## On-/Off-Ramp
 
 This section explains the key concepts for using the DFX on-ramp and off-ramp.

src/config/config.ts

@@ -50,6 +50,7 @@ export class Configuration {
   defaultWalletId = 1;
   transactionRefundExpirySeconds = 300; // 5 minutes - enough time to fill out the refund form
   txRequestWaitingExpiryDays = 7;
+  txRequestValidityMinutes = 30;
   financeLogTotalBalanceChangeLimit = 5000;
   faucetAmount = 20; //CHF
   faucetEnabled = process.env.FAUCET_ENABLED === 'true';

src/main.ts

@@ -3,8 +3,8 @@ import { NestFactory } from '@nestjs/core';
 import { WsAdapter } from '@nestjs/platform-ws';
 import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
 import * as AppInsights from 'applicationinsights';
-import { useContainer } from 'class-validator';
 import { spawnSync } from 'child_process';
+import { useContainer } from 'class-validator';
 import cors from 'cors';
 import { json, raw, text } from 'express';
 import helmet from 'helmet';
@@ -77,7 +77,10 @@ async function bootstrap() {
 
   const swaggerOptions = new DocumentBuilder()
     .setTitle('DFX API')
-    .setDescription(`DFX API ${Config.environment.toUpperCase()} (updated on ${new Date().toLocaleString()})`)
+    .setDescription(
+      `DFX API ${Config.environment.toUpperCase()} (updated on ${new Date().toLocaleString()})\n\n` +
+        '**Amount Convention:** All amount fields use human-readable display units (e.g., 1.5 BTC, not 150,000,000 satoshis). ',
+    )
     .setExternalDoc('Github documentation', Config.social.github)
     .setVersion(Config.defaultVersionString)
     .addBearerAuth()

src/subdomains/core/buy-crypto/routes/buy/dto/buy-payment-info.dto.ts

@@ -45,6 +45,9 @@ export class BuyPaymentInfoDto extends BankInfoDto {
   @ApiProperty({ description: 'UID of the transaction order' })
   uid?: string;
 
+  @ApiPropertyOptional({ description: 'URL to the order status page' })
+  statusUrl?: string;
+
   @ApiProperty({ description: 'Price timestamp' })
   timestamp: Date;
 
@@ -121,4 +124,7 @@ export class BuyPaymentInfoDto extends BankInfoDto {
 
   @ApiPropertyOptional({ description: 'Whether this uses a personal IBAN' })
   isPersonalIban?: boolean;
+
+  @ApiPropertyOptional({ description: 'Expiration timestamp of the quote' })
+  expiryDate?: Date;
 }

src/subdomains/core/buy-crypto/routes/buy/dto/get-buy-quote.dto.ts

@@ -69,4 +69,9 @@ export class GetBuyQuoteDto {
   @IsOptional()
   @IsString()
   country?: string;
+
+  @ApiPropertyOptional({ description: 'State or province code (e.g. US-NY, CA-BC)' })
+  @IsOptional()
+  @IsString()
+  stateProvince?: string;
 }

src/subdomains/core/buy-crypto/routes/swap/dto/swap-payment-info.dto.ts

@@ -15,6 +15,9 @@ export class SwapPaymentInfoDto {
   @ApiProperty({ description: 'UID of the transaction order' })
   uid?: string;
 
+  @ApiPropertyOptional({ description: 'URL to the order status page' })
+  statusUrl?: string;
+
   @ApiProperty({ description: 'Price timestamp' })
   timestamp: Date;
 
@@ -103,4 +106,7 @@ export class SwapPaymentInfoDto {
     description: 'Whether gasless transaction is available for this request',
   })
   gaslessAvailable?: boolean;
+
+  @ApiPropertyOptional({ description: 'Expiration timestamp of the quote' })
+  expiryDate?: Date;
 }

src/subdomains/core/history/dto/history-query.dto.ts

@@ -1,6 +1,6 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import { Type } from 'class-transformer';
-import { IsDate, IsEnum, IsNotEmpty, IsOptional, IsString } from 'class-validator';
+import { IsDate, IsEnum, IsNotEmpty, IsNumber, IsOptional, IsString, Max, Min } from 'class-validator';
 import { Blockchain } from 'src/integration/blockchain/shared/enums/blockchain.enum';
 import { ExportType } from '../services/history.service';
 import { HistoryFilter } from './history-filter.dto';
@@ -32,6 +32,21 @@ export class HistoryQuery extends HistoryFilter {
   @IsOptional()
   @IsString()
   blockchains?: string;
+
+  @ApiPropertyOptional({ description: 'Maximum number of transactions to return', default: 1000 })
+  @IsOptional()
+  @IsNumber()
+  @Min(1)
+  @Max(10000)
+  @Type(() => Number)
+  limit?: number;
+
+  @ApiPropertyOptional({ description: 'Number of transactions to skip', default: 0 })
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  @Type(() => Number)
+  offset?: number;
 }
 
 export class HistoryQueryUser extends HistoryQuery {

src/subdomains/core/history/mappers/transaction-dto.mapper.ts

@@ -111,6 +111,7 @@ export class TransactionDtoMapper {
             asset: buyCrypto.networkStartAsset,
           }
         : null,
+      userCountry: buyCrypto.transaction.userData?.country?.symbol,
     };
 
     return Object.assign(new TransactionDto(), dto);
@@ -181,6 +182,7 @@ export class TransactionDtoMapper {
       chargebackDate: buyFiat.chargebackDate,
       date: buyFiat.transaction.created,
       externalTransactionId: buyFiat.transaction.externalId,
+      userCountry: buyFiat.transaction.userData?.country?.symbol,
     };
 
     return Object.assign(new TransactionDto(), dto);
@@ -241,6 +243,7 @@ export class TransactionDtoMapper {
       date: txRequest.created,
       externalTransactionId: null,
       networkStartTx: null,
+      userCountry: txRequest.user?.userData?.country?.symbol,
     };
 
     return Object.assign(new TransactionDto(), dto);
@@ -303,6 +306,7 @@ export class TransactionDtoMapper {
       chargebackTxUrl: undefined,
       chargebackDate: undefined,
       date: refReward.transaction.created,
+      userCountry: refReward.transaction.userData?.country?.symbol,
     };
 
     return Object.assign(new TransactionDto(), dto);

src/subdomains/core/history/services/history.service.ts

@@ -122,8 +122,14 @@ export class HistoryService {
   ): Promise<{ buyCryptos: BuyCrypto[]; buyFiats: BuyFiat[]; refRewards: RefReward[] }> {
     const transactions =
       user instanceof UserData
-        ? await this.transactionService.getTransactionsForAccount(user.id, query.from, query.to)
-        : await this.transactionService.getTransactionsForUsers([user.id], query.from, query.to);
+        ? await this.transactionService.getTransactionsForAccount(
+            user.id,
+            query.from,
+            query.to,
+            query.limit,
+            query.offset,
+          )
+        : await this.transactionService.getTransactionsForUsers([user.id], query.from, query.to, query.limit);
 
     const all =
       query.buy == null && query.sell == null && query.staking == null && query.ref == null && query.lm == null;

src/subdomains/core/sell-crypto/route/dto/get-sell-quote.dto.ts

@@ -62,4 +62,9 @@ export class GetSellQuoteDto {
   @IsOptional()
   @IsString()
   country?: string;
+
+  @ApiPropertyOptional({ description: 'State or province code (e.g. US-NY, CA-BC)' })
+  @IsOptional()
+  @IsString()
+  stateProvince?: string;
 }