{"id":29880301,"url":"https://github.com/solana-developers/solana-devnet-faucet-backend","last_synced_at":"2026-02-25T07:39:17.915Z","repository":{"id":265341322,"uuid":"885997574","full_name":"solana-developers/solana-devnet-faucet-backend","owner":"solana-developers","description":"temp","archived":false,"fork":false,"pushed_at":"2025-07-23T13:38:09.000Z","size":77,"stargazers_count":0,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-31T11:37:59.447Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/solana-developers.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-11-09T23:06:22.000Z","updated_at":"2025-07-23T13:38:14.000Z","dependencies_parsed_at":"2025-02-16T19:25:49.612Z","dependency_job_id":"50284d24-e9e2-4d6d-91d1-46fe5eec688f","html_url":"https://github.com/solana-developers/solana-devnet-faucet-backend","commit_stats":null,"previous_names":["solana-developers/solana-devnet-faucet-backend"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/solana-developers/solana-devnet-faucet-backend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solana-developers%2Fsolana-devnet-faucet-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solana-developers%2Fsolana-devnet-faucet-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solana-developers%2Fsolana-devnet-faucet-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solana-developers%2Fsolana-devnet-faucet-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/solana-developers","download_url":"https://codeload.github.com/solana-developers/solana-devnet-faucet-backend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solana-developers%2Fsolana-devnet-faucet-backend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29814107,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-25T05:36:42.804Z","status":"ssl_error","status_checked_at":"2026-02-25T05:36:31.934Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-31T09:40:53.106Z","updated_at":"2026-02-25T07:39:17.865Z","avatar_url":"https://github.com/solana-developers.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Faucet Backend API\n\nThis API provides endpoints for interacting with two main tables: `faucet.solana_balances` and `faucet.rate_limits`.\nBelow are the available endpoints for each table.\n\n---\n## Development\n\n1. Clone the repository\n   ```bash\n   git clone \u003crepository-url\u003e\n   ```\n\n2. Install dependencies\n   ```bash\n   yarn install\n   ```\n\n3. Set up your `.env` file with the following\n   ```env\n   POSTGRES_STRING=postgresql://\u003cuser\u003e:\u003cpassword\u003e@\u003chost\u003e:\u003cport\u003e/\u003cdatabase\u003e\n   PROJECT_ID=\u003cGCP Project ID\u003e\n   ```\n   **NOTE** if you want to send request directly to Analytics DB, use [Cloud SQL Auth Proxy](https://cloud.google.com/sql/docs/mysql/sql-proxy) to setup a connection\n   ```\n    ./cloud-sql-proxy --address 0.0.0.0 --port 5434 \u003cSQL DB Connection String\u003e\n    ```\n\n4. **OPTIONAL** In order to test the Github API locally, you need to provide a [Github Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) in your `.env` file. The token only needs `read:user` and `public_repo`\n    ```\n    GH_TOKEN=\u003cGithub Token\u003e\n    ```\n\n5. Start the server\n   ```bash\n   yarn start\n   ```\n\n5. Access the API at `http://localhost:3000/api`.\n\n---\n\n## Solana Balances Endpoints\n\n### **Create a New Solana Balance**\n\n**POST** `/api/solana-balances`\n\n- **Description**: Adds a new Solana account balance.\n- **Request Body**:\n  ```json\n  {\n    \"account\": \"string\",\n    \"balance\": \"number\"\n  }\n  ```\n- **Curl Command**:\n  ```bash\n  curl -v -X POST http://localhost:3000/api/solana-balances \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"account\": \"test_account_1\", \"balance\": 100.50}'\n  ```\n- **Response**:\n  ```json\n  {\n    \"id\": 1,\n    \"account\": \"string\",\n    \"balance\": \"number\",\n    \"date\": \"timestamp\"\n  }\n  ```\n\n### **Get All Balances for an Account**\n\n**GET** `/api/solana-balances/account/:account`\n\n- **Description**: Retrieves all balances for a specific Solana account.\n- **Curl Command**:\n  ```bash\n  curl -v http://localhost:3000/api/solana-balances/account/test_account_1\n  ```\n- **Response**:\n  ```json\n  [\n    {\n      \"id\": 1,\n      \"account\": \"string\",\n      \"balance\": \"number\",\n      \"date\": \"timestamp\"\n    }\n  ]\n  ```\n\n### **Get Recent Balances (Last Month)**\n\n**GET** `/api/solana-balances/recent`\n\n- **Description**: Retrieves all Solana account balances from the past month, ordered by date.\n- **Curl Command**:\n  ```bash\n  curl -v http://localhost:3000/api/solana-balances/recent\n  ```\n- **Response**:\n  ```json\n  [\n    {\n      \"account\": \"string\",\n      \"balance\": \"number\",\n      \"date\": \"timestamp\"\n    }\n  ]\n  ```\n\n---\n\n## Github Validation Endpoints\n\n### **Validate Github User ID**\n\n**GET** `/api/github-validation/:userId`\n\n- **Description**: Validates a Github user by fetching their information from the Github API using their user ID.\n- **Request Params**:\n    - `userId` (string): The Github User ID to validate.\n\n- **Curl Command**:\n  ```bash\n  curl -v http://localhost:3000/api/gh-validation/exampleUser \n  ```\n-**Response**:\n```json\n{\n  \"valid\": \"boolean\"\n} \n```\n\n---\n\n## Transactions Endpoints\n\n### **Create a New Transaction**\n\n**POST** `/api/transactions`\n\n- **Description**: Creates a new transaction entry with a unique signature.\n- **Request Body**:\n  ```json\n  {\n    \"signature\": \"string\",\n    \"ip_address\": \"string\",\n    \"wallet_address\": \"string\",\n    \"github_id\": \"string (optional)\",\n    \"timestamp\": \"number\"\n  }\n  ```\n- **Curl Command**:\n  ```bash\n  curl -v -X POST http://localhost:3000/api/transactions \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\n      \"signature\": \"tx_123\",\n      \"ip_address\": \"192.168.0.1\",\n      \"wallet_address\": \"wallet_abc\",\n      \"github_id\": \"user123\",\n      \"timestamp\": 1714752000\n    }'\n  ```\n- **Response**:\n  ```json\n  {\n    \"signature\": \"tx_123\",\n    \"ip_address\": \"192.168.0.1\",\n    \"wallet_address\": \"wallet_abc\",\n    \"github_id\": \"user123\",\n    \"timestamp\": 1714752000\n  }\n  ```\n\n---\n\n### **Get the Most Recent Transaction(s)**\n\n**GET** `/api/transactions/last`\n\n- **Description**: Retrieves the most recent transaction(s) matching the given query parameters. You must provide at least one of `wallet_address` or `ip_address`.\n- **Query Params**:\n    - `wallet_address` (string, optional)\n    - `github_id` (string, optional)\n    - `ip_address` (string, optional)\n    - `count` (number, optional – number of results to return; defaults to 1)\n\n- **Curl Command**:\n  ```bash\n  curl -v \"http://localhost:3000/api/transactions/last?wallet_address=wallet_abc\u0026count=2\"\n  ```\n- **Response** (if found):\n  ```json\n  [\n    {\n      \"signature\": \"tx_123\",\n      \"ip_address\": \"192.168.0.1\",\n      \"wallet_address\": \"wallet_abc\",\n      \"github_id\": \"user123\",\n      \"timestamp\": 1714752000\n    }\n  ]\n  ```\n\n- **Response** (if not found):\n  ```json\n  {\n    \"message\": \"No transaction found for the given criteria.\"\n  }\n  ```\n\n---\n\n### **Delete a Transaction by Signature**\n\n**DELETE** `/api/transactions/:signature`\n\n- **Description**: Deletes a transaction based on its signature.\n- **Curl Command**:\n  ```bash\n  curl -v -X DELETE http://localhost:3000/api/transactions/tx_123\n  ```\n- **Response** (if deleted):\n  ```json\n  {\n    \"signature\": \"tx_123\",\n    \"ip_address\": \"192.168.0.1\",\n    \"wallet_address\": \"wallet_abc\",\n    \"github_id\": \"user123\",\n    \"timestamp\": 1714752000\n  }\n  ```\n\n- **Response** (if not found):\n  ```json\n  {\n    \"message\": \"Transaction not found\"\n  }\n  ```\n\n---\n\n### **Validate User Information**\n\n**POST** `/api/validate`\n\n- **Description**: Validates a GitHub account and checks the transaction history for the given IP address, wallet address, and GitHub ID.\n\n  #### Validation Criteria:\n    - **GitHub Account**\n        - Must be at least 30 days old\n        - Must have at least 1 public repository\n        - Must be of type `User`\n\n    - **Transaction Limits**\n        - Max 200 transactions per IP address (all-time)\n        - Max 100 transactions per wallet address (all-time)\n        - Max 100 transactions per GitHub ID (all-time)\n        - Max 50 transactions for the combination of all three within the last 30 days\n\n- **Request Body**:\n  ```json\n  {\n    \"ip_address\": \"string\",\n    \"wallet_address\": \"string\",\n    \"github_id\": \"string\"\n  }\n  ```\n\n- **Curl Command**:\n  ```bash\n  curl -v -X POST http://localhost:3000/api/validate -H \"Content-Type: application/json\" -d '{\"ip_address\": \"1234567\", \"wallet_address\": \"some_address\", \"github_id\": \"54321\"}'\n  ```\n\n- **Response (Valid)**:\n  ```json\n  {\n    \"valid\": true,\n    \"reason\": \"\"\n  }\n  ```\n\n- **Response (Invalid)**:\n  ```json\n  {\n    \"valid\": false,\n    \"reason\": \"Transaction history is invalid\"\n  }\n  ```\n\n\n## Error Handling\n\nAll endpoints return appropriate HTTP status codes:\n- `201 Created` for successful creations.\n- `200 OK` for successful data retrieval or updates.\n- `404 Not Found` if the requested resource does not exist.\n- `500 Internal Server Error` for unhandled exceptions.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolana-developers%2Fsolana-devnet-faucet-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolana-developers%2Fsolana-devnet-faucet-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolana-developers%2Fsolana-devnet-faucet-backend/lists"}