Purro Token Price API

A Go backend RESTful API with mini-clean architecture for handling token price data from external APIs.

Features

• Import token prices from Hyperliquid DEX
• Calculate price changes over different time intervals (1h, 4h, 12h, 1d, 7d)
• RESTful API for accessing token data and price changes
• Automatic cleanup of old price data with 7-day retention policy
• Efficient storage with daily historical data points

Setup

Prerequisites

• Go 1.16 or higher
• PostgreSQL 12 or higher

Installation

1. Clone the repository:

   git clone https://github.com/purro-wallet/purro-core.git
   cd purro-core
   

2. Install dependencies:

   go mod tidy
   

3. Configure the application: Edit config/app.ini with your database and API settings.

4. Initialize the database:

   psql -U postgres -d your_database_name -f scripts/init_database.sql
   

5. Import tokens from Hyperliquid:

   go run scripts/hyperliquid_importer.go import-tokens
   

6. Import initial prices:

   go run scripts/hyperliquid_importer.go import-prices
   

Running the Application

Start the API server:

go run main.go

Setting Up Automatic Price Updates

Option 1: Using the daemon mode

Run the importer in daemon mode:

go run scripts/hyperliquid_importer.go daemon

Option 2: Using systemd (Linux)

1. Edit the service file:

   nano scripts/hyperliquid-importer.service
   

   Update the WorkingDirectory path to match your installation.

2. Install the service:

   sudo cp scripts/hyperliquid-importer.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable hyperliquid-importer
   sudo systemctl start hyperliquid-importer
   

Option 3: Using cron

Add a cron job to run the importer every hour:

crontab -e

Add the following line:

0 * * * * cd /path/to/purro-core && /usr/local/go/bin/go run scripts/hyperliquid_importer.go import-prices

Data Retention Policy

To manage database size and performance, the system automatically implements a data retention policy:

• Price data is kept for 7 days by default
• For each token, at least one price point per day is preserved for historical analysis
• Older data is automatically cleaned up after each price update

You can adjust the retention period by modifying the DataRetentionDays constant in price_updater.go.

API Documentation

The API is documented using Swagger/OpenAPI. You can view the interactive documentation by opening docs/swagger/index.html in your web browser.

Using the Swagger UI

You can view the Swagger UI documentation by running:

make serve-docs

This will start a local web server on port 8082. Open your browser to http://localhost:8082 to view the Swagger UI. From there, you can:

1. Explore the available endpoints, request/response formats, and data models
2. Try out API calls directly from the UI
3. See example requests and responses

For more details, see the API Documentation README.

API Endpoints

Token Endpoints

• GET /api/v1/tokens - Get all tokens
• POST /api/v1/tokens - Create a new token
• GET /api/v1/tokens/{id} - Get a token by ID
• PUT /api/v1/tokens/{id} - Update a token

Price Endpoints

• POST /api/v1/tokens/{id}/prices - Add a price for a token
• GET /api/v1/tokens/{id}/prices/latest - Get the latest price for a token
• GET /api/v1/tokens/{id}/price-changes/{interval} - Get price change for a token over an interval
• GET /api/v1/price-changes/{interval} - Get price changes for all tokens over an interval
• POST /api/v1/prices/import - Import token prices
• POST /api/v1/prices/import-from-api - Import token prices from external API
• POST /api/v1/prices/cleanup - Cleanup old price records

Time Interval Endpoints

• GET /api/v1/time-intervals - Get all time intervals

Examples

Get price changes for all tokens over 1 day

curl -X GET http://localhost:8080/api/v1/price-changes/1d

Get price change for BTC over 1 hour

# First, get the token ID for BTC
curl -X GET http://localhost:8080/api/v1/tokens | jq '.data[] | select(.symbol=="BTC")'

# Then, use the token ID to get the price change
curl -X GET http://localhost:8080/api/v1/tokens/123/price-changes/1h

Import prices from Hyperliquid

curl -X POST http://localhost:8080/api/v1/prices/import-from-api

Database Schema

The database schema includes the following tables:

• blockchains - Information about blockchains
• tokens - Information about tokens
• token_prices - Historical price data for tokens
• time_intervals - Predefined time intervals for price change calculations

And the following views:

• v_tokens - Combined token information
• v_latest_token_prices - Latest price for each token

License

MIT License