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.
- Features
- Requirements
- Installation
- Environment Variables
- Running the Server
- API Endpoints
- Caching & Rate Limiting
- RPC Requests & Fallback Logic
- License
- Token Metadata Retrieval: Get metadata for any token from a pre-defined list.
- Whitelist Tokens: Retrieve tokens with associated balances and prices for a given account.
- Token Swap Functionality: Execute swap operations with validation and default slippage.
- NEAR Price Retrieval: Fetch the NEAR token price via external APIs with a database fallback.
- FT Tokens Endpoint: Retrieve fungible token balances with caching.
- Token Balance History: Get historical balance data bundled by period.
- Clear Balance History: Delete all token balance history entries from the database.
- Transactions Transfer History: Retrieve transfer history information from transactions.
- Rate Limiting & CORS: Protect endpoints using rate limits and CORS.
- Security: Utilize Helmet for secure HTTP headers.
- RPC Caching: Use internal caching and fallback mechanisms for RPC requests.
-
Clone the repository:
git clone https://github.com/your-username/near-token-swap-api.git cd near-token-swap-api -
Install dependencies:
npm install
-
Setup environment variables:
Copy the provided
.env.examplefile to.envand configure the variables accordingly.cp .env.example .env
-
Run migrations (if using Prisma):
npx prisma migrate dev
Ensure you have a .env file with the following variables configured:
HOSTNAME=127.0.0.1
PORT=3000
PIKESPEAK_KEY=
DATABASE_URL="postgresql://johndoe:randompassword@localhost:5432/mydb?schema=public"
FASTNEAR_API_KEY=
NEARBLOCKS_API_KEY=
Start the server with:
npm startBy default, the server will run on http://127.0.0.1:3000 (or as specified by the HOSTNAME and PORT variables).
-
Endpoint:
GET /api/token-metadata -
Query Parameters:
token(string, required): The token ID for which to retrieve metadata.
-
Response: JSON object containing metadata for the token.
-
Example:
GET /api/token-metadata?token=near
-
Endpoint:
GET /api/whitelist-tokens -
Optional Query Parameter:
account(string): The NEAR account id to filter tokens.
-
Response: JSON object containing whitelisted tokens along with balances and prices.
-
Example:
GET /api/whitelist-tokens?account=example.near
-
Endpoint:
GET /api/swap -
Required Query Parameters:
accountId(string): The account executing the swap.tokenIn(string): The ID of the token to swap from.tokenOut(string): The token to swap to.amountIn(string): The amount oftokenInbeing swapped.
-
Optional Query Parameter:
slippage(string): The allowable slippage (default: "0.01" for 1%).
-
Response: JSON object containing swap details or error information.
-
Example:
GET /api/swap?accountId=example.near&tokenIn=near&tokenOut=usdt&amountIn=100&slippage=0.02
-
Endpoint:
GET /api/near-price -
Description: Retrieves the current NEAR token price. If external sources fail, it falls back to the latest price stored in the database.
-
Response: NEAR price as a JSON value.
-
Example:
GET /api/near-price
-
Endpoint:
GET /api/ft-tokens -
Query Parameters:
account_id(string, required): The account id to fetch fungible token information.
-
Response: JSON object with FT token details.
-
Example:
GET /api/ft-tokens?account_id=example.near
-
Endpoint:
GET /api/all-token-balance-history -
Query Parameters:
account_id(string, required): The account id whose token balance history is to be fetched.token_id(string, required): The token id for which balance history is required.disableCache(optional): When provided, bypasses the cached result (note: sensitive to frequent requests).
-
Response: JSON object mapping each period to its corresponding balance history.
-
Example:
GET /api/all-token-balance-history?account_id=example.near&token_id=near GET /api/all-token-balance-history?account_id=example.near&token_id=near&disableCache=true
-
Endpoint:
DELETE /api/clear-token-balance-history -
Description: Removes all
TokenBalanceHistoryrecords from the database. -
Response: JSON message confirming deletion.
-
Example:
DELETE /api/clear-token-balance-history
-
Endpoint:
GET /api/transactions-transfer-history -
Query Parameters:
treasuryDaoID(string, required): The treasury DAO ID to filter transfer transactions.
-
Response: JSON object containing the transfer history data.
-
Example:
GET /api/transactions-transfer-history?treasuryDaoID=dao.near
-
Caching:
- The API uses NodeCache to store short-term responses (e.g., NEAR prices and token balance histories) to reduce external API calls and recomputation.
- RPC calls (in
src/utils/fetch-from-rpc.ts) also cache responses and skip endpoints temporarily on rate-limited (HTTP 429) responses.
-
Rate Limiting:
- All
/api/*endpoints are limited to 180 requests per 30 seconds per IP (or forwarded IP when available). - This helps protect against abuse and ensures service stability.
- All
- The API makes use of multiple RPC endpoints for querying the NEAR blockchain.
- In
src/utils/fetch-from-rpc.ts, the request is:- Cached based on a hash of the request body.
- Attempted sequentially across a list of primary or archival endpoints.
- The response is stored using Prisma if successful.
- In the event of a known error (e.g., non-existent account), the system caches the fact to avoid unnecessary calls.
This project is licensed under the MIT License. See LICENSE for more details.
For additional questions or contributions, please open an issue or submit a PR on GitHub.