Skip to content

Commit 6dd16f1

Browse files
TguntenaarTguntenaar
committed
update README.md
1 parent 9145e0e commit 6dd16f1

File tree

2 files changed

+247
-15
lines changed

2 files changed

+247
-15
lines changed

‎.env.example‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,5 @@ HOSTNAME=127.0.0.1
22
PORT=3000
33
PIKESPEAK_KEY=
44
DATABASE_URL="postgresql://johndoe:randompassword@localhost:5432/mydb?schema=public"
5+
FASTNEAR_API_KEY=
6+
NEARBLOCKS_API_KEY=

‎README.md‎

Lines changed: 245 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,260 @@
11
# NEAR Token Swap API
22

3-
A RESTful API service for token swaps and metadata on the NEAR blockchain, built with Express.js and TypeScript.
3+
A RESTful API service for token swaps and blockchain metadata on the NEAR network, built with Express.js and TypeScript. It leverages caching, rate limiting, and secure request handling to provide a robust service for interacting with NEAR blockchain data.
4+
5+
---
6+
7+
## Table of Contents
8+
9+
- [Features](#features)
10+
- [Requirements](#requirements)
11+
- [Installation](#installation)
12+
- [Environment Variables](#environment-variables)
13+
- [Running the Server](#running-the-server)
14+
- [API Endpoints](#api-endpoints)
15+
- [Get Token Metadata](#get-token-metadata)
16+
- [Whitelist Tokens](#whitelist-tokens)
17+
- [Token Swap](#token-swap)
18+
- [Get NEAR Price](#get-near-price)
19+
- [Fetch FT Tokens](#fetch-ft-tokens)
20+
- [Get All Token Balance History](#get-all-token-balance-history)
21+
- [Clear Token Balance History](#clear-token-balance-history)
22+
- [Transactions Transfer History](#transactions-transfer-history)
23+
- [Caching & Rate Limiting](#caching--rate-limiting)
24+
- [RPC Requests & Fallback Logic](#rpc-requests--fallback-logic)
25+
- [License](#license)
26+
27+
---
428

529
## Features
630

7-
- Token metadata retrieval
8-
- Whitelist tokens with balances and prices
9-
- Token swap functionality
10-
- Rate limiting
11-
- CORS enabled
12-
- Security headers with Helmet
31+
- **Token Metadata Retrieval:** Get metadata for any token from a pre-defined list.
32+
- **Whitelist Tokens:** Retrieve tokens with associated balances and prices for a given account.
33+
- **Token Swap Functionality:** Execute swap operations with validation and default slippage.
34+
- **NEAR Price Retrieval:** Fetch the NEAR token price via external APIs with a database fallback.
35+
- **FT Tokens Endpoint:** Retrieve fungible token balances with caching.
36+
- **Token Balance History:** Get historical balance data bundled by period.
37+
- **Clear Balance History:** Delete all token balance history entries from the database.
38+
- **Transactions Transfer History:** Retrieve transfer history information from transactions.
39+
- **Rate Limiting & CORS:** Protect endpoints using rate limits and CORS.
40+
- **Security:** Utilize Helmet for secure HTTP headers.
41+
- **RPC Caching:** Use internal caching and fallback mechanisms for RPC requests.
42+
43+
---
44+
45+
## Requirements
46+
47+
- [Node.js](https://nodejs.org/en/) (v14+ recommended)
48+
- [npm](https://www.npmjs.com/) or [yarn](https://yarnpkg.com/)
49+
- A running PostgreSQL database instance
50+
51+
---
52+
53+
## Installation
54+
55+
1. **Clone the repository:**
56+
57+
```bash
58+
git clone https://github.com/your-username/near-token-swap-api.git
59+
cd near-token-swap-api
60+
```
61+
62+
2. **Install dependencies:**
63+
64+
```bash
65+
npm install
66+
```
67+
68+
3. **Setup environment variables:**
69+
70+
Copy the provided `.env.example` file to `.env` and configure the variables accordingly.
71+
72+
```bash
73+
cp .env.example .env
74+
```
75+
76+
4. **Run migrations (if using Prisma):**
77+
78+
```bash
79+
npx prisma migrate dev
80+
```
81+
82+
---
83+
84+
## Environment Variables
85+
86+
Ensure you have a `.env` file with the following variables configured:
87+
88+
```
89+
HOSTNAME=127.0.0.1
90+
PORT=3000
91+
PIKESPEAK_KEY=
92+
DATABASE_URL="postgresql://johndoe:randompassword@localhost:5432/mydb?schema=public"
93+
FASTNEAR_API_KEY=
94+
NEARBLOCKS_API_KEY=
95+
```
96+
97+
---
98+
99+
## Running the Server
100+
101+
Start the server with:
102+
103+
```bash
104+
npm start
105+
```
106+
107+
By default, the server will run on `http://127.0.0.1:3000` (or as specified by the `HOSTNAME` and `PORT` variables).
108+
109+
---
13110

14111
## API Endpoints
15112

16113
### Get Token Metadata
17114

18-
```http
19-
GET /api/token-metadata
20-
```
115+
- **Endpoint:** `GET /api/token-metadata`
116+
- **Query Parameters:**
117+
- `token` (string, required): The token ID for which to retrieve metadata.
118+
- **Response:** JSON object containing metadata for the token.
119+
- **Example:**
120+
121+
```http
122+
GET /api/token-metadata?token=near
123+
```
124+
125+
---
126+
127+
### Whitelist Tokens
128+
129+
- **Endpoint:** `GET /api/whitelist-tokens`
130+
- **Optional Query Parameter:**
131+
- `account` (string): The NEAR account id to filter tokens.
132+
- **Response:** JSON object containing whitelisted tokens along with balances and prices.
133+
- **Example:**
134+
135+
```http
136+
GET /api/whitelist-tokens?account=example.near
137+
```
138+
139+
---
140+
141+
### Token Swap
142+
143+
- **Endpoint:** `GET /api/swap`
144+
- **Required Query Parameters:**
145+
- `accountId` (string): The account executing the swap.
146+
- `tokenIn` (string): The ID of the token to swap from.
147+
- `tokenOut` (string): The token to swap to.
148+
- `amountIn` (string): The amount of `tokenIn` being swapped.
149+
- **Optional Query Parameter:**
150+
- `slippage` (string): The allowable slippage (default: "0.01" for 1%).
151+
- **Response:** JSON object containing swap details or error information.
152+
- **Example:**
153+
154+
```http
155+
GET /api/swap?accountId=example.near&tokenIn=near&tokenOut=usdt&amountIn=100&slippage=0.02
156+
```
157+
158+
---
159+
160+
### Get NEAR Price
161+
162+
- **Endpoint:** `GET /api/near-price`
163+
- **Description:** Retrieves the current NEAR token price. If external sources fail, it falls back to the latest price stored in the database.
164+
- **Response:** NEAR price as a JSON value.
165+
- **Example:**
166+
167+
```http
168+
GET /api/near-price
169+
```
170+
171+
---
172+
173+
### Fetch FT Tokens
174+
175+
- **Endpoint:** `GET /api/ft-tokens`
176+
- **Query Parameters:**
177+
- `account_id` (string, required): The account id to fetch fungible token information.
178+
- **Response:** JSON object with FT token details.
179+
- **Example:**
180+
181+
```http
182+
GET /api/ft-tokens?account_id=example.near
183+
```
184+
185+
---
186+
187+
### Get All Token Balance History
188+
189+
- **Endpoint:** `GET /api/all-token-balance-history`
190+
- **Query Parameters:**
191+
- `account_id` (string, required): The account id whose token balance history is to be fetched.
192+
- `token_id` (string, required): The token id for which balance history is required.
193+
- `disableCache` (optional): When provided, bypasses the cached result (note: sensitive to frequent requests).
194+
- **Response:** JSON object mapping each period to its corresponding balance history.
195+
- **Example:**
196+
197+
```http
198+
GET /api/all-token-balance-history?account_id=example.near&token_id=near
199+
GET /api/all-token-balance-history?account_id=example.near&token_id=near&disableCache=true
200+
```
201+
202+
---
203+
204+
### Clear Token Balance History
205+
206+
- **Endpoint:** `DELETE /api/clear-token-balance-history`
207+
- **Description:** Removes all `TokenBalanceHistory` records from the database.
208+
- **Response:** JSON message confirming deletion.
209+
- **Example:**
210+
211+
```http
212+
DELETE /api/clear-token-balance-history
213+
```
214+
215+
---
216+
217+
### Transactions Transfer History
218+
219+
- **Endpoint:** `GET /api/transactions-transfer-history`
220+
- **Query Parameters:**
221+
- `treasuryDaoID` (string, required): The treasury DAO ID to filter transfer transactions.
222+
- **Response:** JSON object containing the transfer history data.
223+
- **Example:**
224+
225+
```http
226+
GET /api/transactions-transfer-history?treasuryDaoID=dao.near
227+
```
228+
229+
---
230+
231+
## Caching & Rate Limiting
232+
233+
- **Caching:**
234+
- The API uses [NodeCache](https://www.npmjs.com/package/node-cache) to store short-term responses (e.g., NEAR prices and token balance histories) to reduce external API calls and recomputation.
235+
- RPC calls (in `src/utils/fetch-from-rpc.ts`) also cache responses and skip endpoints temporarily on rate-limited (HTTP 429) responses.
236+
237+
- **Rate Limiting:**
238+
- All `/api/*` endpoints are limited to 180 requests per 30 seconds per IP (or forwarded IP when available).
239+
- This helps protect against abuse and ensures service stability.
240+
241+
---
242+
243+
## RPC Requests & Fallback Logic
244+
245+
- The API makes use of multiple RPC endpoints for querying the NEAR blockchain.
246+
- In `src/utils/fetch-from-rpc.ts`, the request is:
247+
- Cached based on a hash of the request body.
248+
- Attempted sequentially across a list of primary or archival endpoints.
249+
- The response is stored using Prisma if successful.
250+
- In the event of a known error (e.g., non-existent account), the system caches the fact to avoid unnecessary calls.
21251

22-
Retrieve metadata for a specific token.
252+
---
23253

24-
#### Query Parameters
254+
## License
25255

26-
- `token` (string, required): The ID of the token for which metadata is requested.
256+
This project is licensed under the MIT License. See [LICENSE](LICENSE) for more details.
27257

28-
#### Response
258+
---
29259

30-
Returns a JSON object containing the metadata of the specified token.
260+
*For additional questions or contributions, please open an issue or submit a PR on GitHub.*

0 commit comments

Comments
 (0)