Crypto-to-INR Transaction API

A high-performance API built with Bun and TypeScript for processing crypto-to-UPI payments using Cardano blockchain technology.

🚀 Features

Crypto-to-UPI Payments: Convert ADA, USDC, USDT to INR via UPI
Smart Contract Integration: Plutus smart contracts for secure escrow
Liquidity Pool Management: Dynamic exchange rates and pool balancing
Credit Scoring: Web3 credit scoring with Midnight privacy layer
Real-time Processing: Fast transaction processing with background tasks
Comprehensive API: RESTful endpoints with OpenAPI documentation

🏗️ Architecture

System Flow

The system follows the sequence diagram provided, implementing:

Payment Initiation: User scans UPI QR, app calculates crypto amount
Crypto Locking: User locks crypto in Plutus smart contract
UPI Processing: System processes UPI payment to merchant
Settlement: Crypto released to liquidity pool, transaction completed
Credit Scoring: Background credit score update using AI and Midnight

Code Architecture

The API follows a clean, layered architecture pattern:

src/
├── controllers/          # Request/Response handling
│   ├── transaction.controller.ts
│   ├── webhook.controller.ts
│   └── health.controller.ts
├── services/            # Business logic layer
│   ├── transaction-orchestrator.service.ts
│   ├── smart-contract.service.ts
│   ├── liquidity-pool.service.ts
│   ├── upi-gateway.service.ts
│   └── credit-score.service.ts
├── repositories/        # Data access layer
│   └── transaction.repository.ts
├── routes/             # API route definitions
│   ├── transaction.routes.ts
│   ├── webhook.routes.ts
│   ├── health.routes.ts
│   └── stats.routes.ts
├── models/             # TypeScript interfaces
│   └── transaction.ts
├── types/              # Enums and type definitions
│   └── enums.ts
├── utils/              # Utility functions
│   ├── validation.ts
│   └── error-handler.ts
└── index.ts           # Main application entry point

Layer Responsibilities:

Controllers: Handle HTTP requests/responses, input validation, error handling
Services: Implement business logic, coordinate between different systems
Repositories: Manage data persistence and retrieval
Routes: Define API endpoints and request/response schemas
Models: TypeScript interfaces for data structures
Utils: Shared utilities for validation, error handling, etc.

📋 Prerequisites

Bun runtime (v1.0+)
Node.js 18+ (for compatibility)
PostgreSQL 14+ (for production)
Cardano node access (Blockfrost/Koios)

🛠️ Installation

Clone the repository

git clone <repository-url>
cd crypto-to-inr-api

Install dependencies
```
bun install
```

Set up environment variables

cp env.example .env
# Edit .env with your configuration

Test the controller architecture
```
bun run test-controllers.ts
```
Run the development server
```
bun run dev
```

🔧 Configuration

Environment Variables

Copy env.example to .env and configure:

Server: PORT, NODE_ENV
Database: PostgreSQL connection details
Blockchain: Cardano network, Blockfrost API key
UPI Gateway: Banking partner API credentials
Services: AI engine, Midnight network APIs

Database Setup

For production, set up PostgreSQL with the schema:

-- See the schema in the LLD comments
-- Tables: transactions, liquidity_pool, exchange_rates

📖 API Documentation

Start the server and visit:

Swagger UI: http://localhost:3000/swagger
Health Check: http://localhost:3000/health

Core Endpoints

1. Initiate Payment

POST /api/v1/transactions/initiate
Content-Type: application/json

{
  "user_wallet_address": "addr1...",
  "merchant_upi_id": "merchant@paytm",
  "amount_inr": 1000.00,
  "crypto_asset": "ADA"
}

2. Confirm Crypto Lock

POST /api/v1/transactions/lock
Content-Type: application/json

{
  "transaction_id": "uuid",
  "cardano_tx_hash": "64-char-hex",
  "signed_by_wallet": "addr1..."
}

3. Get Transaction Status

GET /api/v1/transactions/{id}

🔄 Transaction Flow

Initiation
- Validate request parameters
- Check liquidity pool availability
- Calculate crypto amount + fees
- Generate smart contract address
- Return payment details
Crypto Lock
- Verify blockchain transaction
- Update transaction status
- Trigger UPI payment (background)
UPI Processing (Background)
- Reserve INR from pool
- Initiate UPI payment
- Handle success/failure
- Release crypto to pool or refund
Completion
- Update transaction status
- Trigger credit score update
- Send notifications

🧪 Testing

# Run tests
bun test

# Test specific endpoint
curl -X POST http://localhost:3000/api/v1/transactions/initiate \
  -H "Content-Type: application/json" \
  -d '{
    "user_wallet_address": "addr1test123...",
    "merchant_upi_id": "test@paytm",
    "amount_inr": 100,
    "crypto_asset": "ADA"
  }'

🔐 Security

Input validation and sanitization
Rate limiting (100 requests/minute)
CORS configuration
Environment-based secrets
Error handling without data leakage

📊 Monitoring

Health check endpoints
Transaction statistics
Service status monitoring
Error logging and tracking

🚀 Deployment

Development

bun run dev

Production

bun run build
bun run start

Docker (Optional)

FROM oven/bun:1
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install
COPY . .
EXPOSE 3000
CMD ["bun", "run", "start"]

🔧 Services Integration

Cardano Blockchain

Blockfrost API: Blockchain queries and transaction submission
Koios API: Alternative blockchain data source
Plutus Scripts: Smart contract deployment and interaction

UPI Gateway

Banking Partner API: UPI payment processing
NPCI Integration: Direct UPI network access
Webhook Handling: Real-time payment status updates

AI Credit Scoring

Transaction Analysis: Pattern recognition and risk assessment
Midnight Privacy: Zero-knowledge proofs for sensitive data
On-chain Storage: Encrypted credit scores on Cardano

📈 Performance

Bun Runtime: 3x faster than Node.js
Async Processing: Background UPI payment handling
Connection Pooling: Efficient database connections
Caching: Exchange rate and pool balance caching

🐛 Troubleshooting

Common Issues

Bun Installation: Use official installer from bun.sh
SSL Certificates: Configure for production deployment
Database Connection: Check PostgreSQL credentials
API Keys: Verify Blockfrost and UPI gateway keys

Logs

Check application logs for detailed error information:

# Development
bun run dev

# Production logs
tail -f /var/log/crypto-upi-api.log

🤝 Contributing

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support and questions:

Create an issue in the repository
Check the API documentation at /swagger
Review the troubleshooting section above

🔮 Roadmap

Wallet Score API

A CIBIL-like credit scoring system for cryptocurrency wallets using Covalent APIs. This service analyzes wallet activity across multiple blockchain networks and calculates a comprehensive wallet score (0-850).

Features

Multi-chain Analysis: Analyzes wallet data across 8 major blockchain networks
- Ethereum (1)
- Linea (59144)
- Base (8453)
- Arbitrum (42161)
- BNB Chain (56)
- Optimism (10)
- Polygon (137)
- Sei (1329)
Comprehensive Scoring: Evaluates wallets based on:
- Total Balance (30% weight)
- Portfolio Diversity (20% weight)
- Transaction Activity (20% weight)
- NFT Ownership (10% weight)
- Chain Diversity (10% weight)
- Portfolio Stability (10% weight)

Installation

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env

# Update your Covalent API key in .env

Running the Application

# Development mode with hot reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

The server will start on http://localhost:3000

API Endpoints

1. Get Wallet Score

Endpoint: GET /api/wallet-score/:walletAddress

Description: Returns the calculated wallet score and breakdown

Example:

curl http://localhost:3000/api/wallet-score/0xd362b7e73aed6d097bf7a2032d6ee6a25d91f368

Response:

{
  "success": true,
  "data": {
    "walletAddress": "0xd362b7e73aed6d097bf7a2032d6ee6a25d91f368",
    "totalScore": 125,
    "scoreBreakdown": {
      "totalBalanceScore": 0,
      "portfolioDiversityScore": 0,
      "transactionActivityScore": 0,
      "nftOwnershipScore": 0,
      "chainDiversityScore": 20,
      "portfolioStabilityScore": 50
    },
    "grade": "Very Poor",
    "chainsAnalyzed": [1, 59144, 8453, 42161, 56, 10, 137, 1329],
    "timestamp": "2025-11-29T10:55:00.000Z"
  }
}

2. Get Wallet Score with Details

Endpoint: GET /api/wallet-score/:walletAddress/details

Description: Returns the wallet score along with raw API responses from all chains

Example:

curl http://localhost:3000/api/wallet-score/0xd362b7e73aed6d097bf7a2032d6ee6a25d91f368/details

3. Health Check

Endpoint: GET /health

Description: Check if the API is running

Example:

curl http://localhost:3000/health

Score Grading System

Score Range	Grade
750-850	Excellent
650-749	Very Good
550-649	Good
450-549	Fair
350-449	Poor
0-349	Very Poor

Score Components

1. Total Balance Score (30%)

Evaluates the total USD value across all chains
Uses logarithmic scaling to handle varying wallet sizes
Filters out spam tokens and dust

2. Portfolio Diversity Score (20%)

Measures the number of unique, valuable tokens held
Rewards multi-token portfolios
Ignores spam and low-value tokens

3. Transaction Activity Score (20%)

Analyzes transaction count and success rate
Higher activity and success rates yield better scores
Considers transaction patterns across all chains

4. NFT Ownership Score (10%)

Evaluates NFT holdings across chains
Rewards NFT diversity

5. Chain Diversity Score (10%)

Measures wallet activity across multiple blockchains
Rewards cross-chain engagement

6. Portfolio Stability Score (10%)

Analyzes portfolio value volatility over time
Lower volatility indicates better stability
Uses 30-day historical data

Project Structure

cardano/
├── src/
│   ├── controllers/
│   │   └── walletScoreController.ts
│   ├── services/
│   │   ├── covalentService.ts
│   │   └── walletScoreService.ts
│   ├── routes/
│   │   └── walletScoreRoutes.ts
│   └── server.ts
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

Environment Variables

PORT: Server port (default: 3000)
COVALENT_API_KEY: Your Covalent API key

Error Handling

The API returns appropriate HTTP status codes:

200: Success
400: Bad request (invalid wallet address)
404: Route not found
500: Internal server error

Notes

All wallet addresses must be valid Ethereum-style addresses (0x followed by 40 hexadecimal characters)
API calls to Covalent are made in parallel for better performance
Failed chain queries don't block the overall score calculation
Scores are calculated in real-time on each request

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.cursor/rules		.cursor/rules
.idea		.idea
CryptoPi-frontend		CryptoPi-frontend
prisma		prisma
src		src
.bunfig.toml		.bunfig.toml
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
SSL_FIX_GUIDE.md		SSL_FIX_GUIDE.md
USER_API_GUIDE.md		USER_API_GUIDE.md
bun.lock		bun.lock
database-schema.sql		database-schema.sql
env.example		env.example
index.ts		index.ts
package.json		package.json
tsconfig.json		tsconfig.json

nayanprasad/crypto-pi

Folders and files

Latest commit

History

Repository files navigation

Crypto-to-INR Transaction API

🚀 Features

🏗️ Architecture

System Flow

Code Architecture

📋 Prerequisites

🛠️ Installation

🔧 Configuration

Environment Variables

Database Setup

📖 API Documentation

Core Endpoints

1. Initiate Payment

2. Confirm Crypto Lock

3. Get Transaction Status

🔄 Transaction Flow

🧪 Testing

🔐 Security

📊 Monitoring

🚀 Deployment

Development

Production

Docker (Optional)

🔧 Services Integration

Cardano Blockchain

UPI Gateway

AI Credit Scoring

📈 Performance

🐛 Troubleshooting

Common Issues

Logs

🤝 Contributing

📄 License

🆘 Support

🔮 Roadmap

Wallet Score API

Features

Installation

Running the Application

API Endpoints

1. Get Wallet Score

2. Get Wallet Score with Details

3. Health Check

Score Grading System

Score Components

1. Total Balance Score (30%)

2. Portfolio Diversity Score (20%)

3. Transaction Activity Score (20%)

4. NFT Ownership Score (10%)

5. Chain Diversity Score (10%)

6. Portfolio Stability Score (10%)

Project Structure

Environment Variables

Error Handling

Notes

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages