Skip to main content

​
Quickstart Guide

This guide will have you querying cryptocurrency prices in under 5 minutes using Docker Compose.

​
Prerequisites

Before starting, ensure you have:
  • Docker and Docker Compose installed
  • A CoinGecko API key (get one free here)
  • Basic familiarity with REST APIs and curl/Postman
This quickstart uses Docker Compose to run PostgreSQL, Redis, and the CryptoPulse API as a single stack. No local Node.js installation required!

​
Step-by-Step Setup

1

Clone the Repository

git clone <repository-url>
cd crypto-pulse
2

Configure Environment

Copy the example environment file and update it with your settings:
cp .env.example .env
Edit .env and set your CoinGecko API key:
.env
PORT=3000

ADMIN_USER=admin
ADMIN_PASS=secret
JWT_SECRET=change-me-to-a-secure-random-string
JWT_EXPIRES_IN=1h

# Docker service names (postgres/redis) are used for inter-container networking
DATABASE_URL=postgres://postgres:postgres@postgres:5432/crypto_pulse
REDIS_URL=redis://redis:6379

COINGECKO_API_KEY=your-api-key-here
COINGECKO_BASE_URL=https://api.coingecko.com
Replace JWT_SECRET with a strong random string in production. Never commit secrets to version control.
3

Start the Services

Launch PostgreSQL, Redis, and the API with a single command:
docker compose up --build
Wait for the health checks to pass. You should see:
✔ Container crypto-pulse-postgres-1  Healthy
✔ Container crypto-pulse-redis-1     Healthy
✔ Container crypto-pulse-api-1       Started
The API will be available at http://localhost:3000
4

Authenticate and Get a Token

Use the credentials from your .env file to login:
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "secret"
  }'
Response:
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": "1h"
}
Copy the accessToken value for the next step.
5

Query Your First Price

Use the token to get Bitcoin’s current price:
curl http://localhost:3000/v1/price/bitcoin \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
Response:
{
  "coinId": "bitcoin",
  "vsCurrency": "usd",
  "price": 67210.45,
  "fetchedAt": "2026-03-04T17:30:00.000Z"
}
6

Explore the Interactive Docs

Open http://localhost:3000/docs in your browser.Click the Authorize button in the top right, enter Bearer YOUR_TOKEN, and you can test all endpoints interactively.
The Swagger UI includes full request/response schemas, example values, and documented error codes for every endpoint.

​
Testing Request Batching

To see batching in action, send multiple requests for the same coin within the 5-second window: 
# Terminal 1
curl http://localhost:3000/v1/price/ethereum \
  -H "Authorization: Bearer YOUR_TOKEN" &

# Terminal 2 (within 5 seconds)
curl http://localhost:3000/v1/price/ethereum \
  -H "Authorization: Bearer YOUR_TOKEN" &

# Terminal 3 (within 5 seconds)
curl http://localhost:3000/v1/price/ethereum \
  -H "Authorization: Bearer YOUR_TOKEN" &
Check the API logs - you’ll see only one CoinGecko API call was made, but all three requests received the same response.

​
Querying Price History

After making a few price requests, query the historical data: 
curl "http://localhost:3000/v1/price/bitcoin/history?limit=5&page=1" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response: 
{
  "coinId": "bitcoin",
  "vsCurrency": "usd",
  "items": [
    { "price": 67210.45, "fetchedAt": "2026-03-04T17:30:00.000Z" },
    { "price": 67101.22, "fetchedAt": "2026-03-04T17:25:00.000Z" }
  ],
  "page": 1,
  "limit": 5,
  "totalItems": 2,
  "totalPages": 1,
  "hasNextPage": false
}

​
Date Range Filtering

Filter by date range using ISO 8601 format: 
curl "http://localhost:3000/v1/price/bitcoin/history?from=2026-03-01T00:00:00Z&to=2026-03-05T00:00:00Z" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Common Issues

Your token may have expired (default: 1 hour). Run the login request again to get a fresh token.
Redis or PostgreSQL may not be healthy. Run docker compose ps to check service status and docker compose logs to see error details.
You’ve hit the throttle limit (default: 20 requests per 60 seconds). Wait a minute or adjust THROTTLE_GLOBAL_LIMIT in .env.
The coin ID doesn’t exist in CoinGecko. Use lowercase names like bitcoin, ethereum, cardano. Check CoinGecko’s coin list.

​
Stopping the Services

When you’re done: 
# Stop containers but keep data
docker compose down

# Stop and remove all data (including PostgreSQL volumes)
docker compose down -v

​
Next Steps

Installation Guide

Learn about local development setup and multi-instance deployments

API Reference

Explore all endpoints, parameters, and error codes in detail

Configuration

Customize batching behavior, rate limits, and more

Architecture

Deep dive into how batching and coordination work

Build docs developers (and LLMs) love

Get started for freeTalk to us