This is the backend API for YapBay, a peer-to-peer cryptocurrency trading platform that facilitates secure exchanges between crypto and fiat currencies. The platform utilizes blockchain-based smart contracts for escrow services, ensuring secure and trustless transactions.
The primary repo for this project is at https://github.com/Panmoni/yapbay.
For detailed project requirements and specifications, see Project Requirements.
YapBay is a platform that supports both single-leg trades (simple crypto-to-fiat exchanges) and sequential trades (multi-leg transactions that enable fiat-to-fiat exchanges through crypto as an intermediary).
The YapBay platform consists of the following key components:
- Smart Contract Layer: Solana-based escrow contracts that handle the secure holding and release of cryptocurrency funds
- Database Layer: PostgreSQL database that stores user accounts, trade information, and dispute records
- API Layer: Node.js/Express backend that connects the blockchain and database layers
- Client Applications: Web and mobile interfaces that interact with the API
The YapBay API provides endpoints for:
- User account management
- Creating and managing offers
- Initiating and completing trades
- Escrow operations (create, fund, release, cancel)
- Dispute handling and resolution
- Interacting with the YapBayEscrow smart contract on Solana devnet
- Node.js (v18 or higher)
- PostgreSQL database
- Solana testnet account with USDC tokens
- Private key for a funded Solana account
- Clone the repository:
git clone https://github.com/Panmoni/yapbay-api.git
cd yapbay-api- Install dependencies:
npm install- Set up environment variables:
Create a
.envfile in the root directory with the following variables:
RPC_URL=
CONTRACT_ADDRESS=
ARBITRATOR_ADDRESS=
POSTGRES_URL=postgres://username:password@localhost:5432/yapbay
JWT_SECRET=your-jwt-secret
PRIVATE_KEY=your-private-key
PORT=3000
- Set up the database:
psql -U your_username -d your_database -a -f schema.sql- Test the blockchain connection:
npm run test:connection- Build the project:
npm run build- Start the server:
# Start the server
npm startFor development:
npm run start:dev
## API Endpoints
### Authentication
All authenticated endpoints require a JWT token in the Authorization header:
Authorization: Bearer your-jwt-token
### Accounts
- `POST /accounts` - Create a new account
- `GET /accounts/me` - Get authenticated user's account
- `GET /accounts/:id` - Get account by ID
- `PUT /accounts/:id` - Update account
### Offers
- `POST /offers` - Create a new offer
- `GET /offers` - List offers (with optional filters)
- `GET /offers/:id` - Get offer details
- `PUT /offers/:id` - Update an offer
- `DELETE /offers/:id` - Delete an offer
### Trades
- `POST /trades` - Initiate a trade
- `GET /trades` - List trades (with optional filters)
- `GET /my/trades` - List authenticated user's trades
- `GET /trades/:id` - Get trade details
- `PUT /trades/:id` - Update trade info
### Escrows
- `POST /escrows/create` - Create a new escrow
- `POST /escrows/fund` - Fund an escrow
- `GET /escrows/:trade_id` - Get escrow details by trade ID
- `GET /my/escrows` - Get authenticated user's escrows
- `POST /escrows/release` - Release an escrow
- `POST /escrows/cancel` - Cancel an escrow
- `POST /escrows/dispute` - Open a dispute
## Smart Contract Interaction
The API interacts with the YapBayEscrow smart contract. The contract handles:
- Creating escrows between buyers and sellers
- Funding escrows with USDC
- Marking fiat as paid
- Releasing funds to the buyer
- Cancelling escrows when conditions are not met
- Handling disputes with bond requirements
- Supporting sequential escrows (linked trades)
Key contract functions include:
- `createEscrow`: Initializes a new escrow agreement
- `fundEscrow`: Deposits cryptocurrency into the escrow
- `markFiatPaid`: Confirms fiat payment has been made
- `releaseEscrow`: Releases funds to the buyer
- `cancelEscrow`: Cancels the escrow and returns funds to the seller
- `openDisputeWithBond`: Initiates a dispute with a bond requirement
- `respondToDisputeWithBond`: Responds to a dispute with evidence
- `resolveDisputeWithExplanation`: Resolves a dispute with arbitrator decision
## Development
### Running Tests
```bash
# Run all tests
npm test
# Run blockchain-related tests
npm run test:blockchain
# Test blockchain connection
npm run test:connection
npm run lint- JWT-based authentication and authorization
- Secure blockchain key management
- Transaction verification
- Data encryption for sensitive information
- Rate limiting and input validation
- HTTPS enforcement
- Maximum escrow amount is limited to 100 USDC per trade for security reasons
- Dispute resolution requires bond deposits from both parties
- Time limits for escrow operations are enforced by the smart contract
- Sequential trades must be properly linked to ensure atomic execution
This project is licensed under the MIT License.