{"id":25812165,"url":"https://github.com/astralprotocol/api","last_synced_at":"2026-03-07T14:30:59.074Z","repository":{"id":279544652,"uuid":"938124386","full_name":"AstralProtocol/api","owner":"AstralProtocol","description":"The Astral API","archived":false,"fork":false,"pushed_at":"2025-03-03T12:37:41.000Z","size":288,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-08T08:25:30.038Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/AstralProtocol.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}},"created_at":"2025-02-24T13:11:12.000Z","updated_at":"2025-03-03T12:37:45.000Z","dependencies_parsed_at":"2025-02-26T06:06:17.333Z","dependency_job_id":"a5b4b0cd-683d-4fd9-a91e-ce60b0d718e8","html_url":"https://github.com/AstralProtocol/api","commit_stats":null,"previous_names":["astralprotocol/api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AstralProtocol/api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AstralProtocol%2Fapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AstralProtocol%2Fapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AstralProtocol%2Fapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AstralProtocol%2Fapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AstralProtocol","download_url":"https://codeload.github.com/AstralProtocol/api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AstralProtocol%2Fapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30217420,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T14:02:48.375Z","status":"ssl_error","status_checked_at":"2026-03-07T14:02:43.192Z","response_time":53,"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-02-28T01:44:57.353Z","updated_at":"2026-03-07T14:30:59.039Z","avatar_url":"https://github.com/AstralProtocol.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Astral API\n\nA decentralized geospatial data API that integrates with Ethereum Attestation Service (EAS) to provide verifiable location proofs.\n\n## Features\n\n- EAS attestations as location proofs\n- OGC API Features compliance\n- PostGIS-powered spatial queries\n- Web3 authentication\n- GraphQL proxy layer\n\n## API Endpoints\n\n### Health Check\n- `GET /health`\n  - Returns API health status\n  - Response: `{\"status\": \"healthy\"}`\n\n### Location Proofs (OGC API - Features)\n- `GET /collections`\n  - Lists available collections\n  - Response: List of collections with metadata\n\n- `GET /collections/{collection_id}/items`\n  - Retrieves features from a specific collection\n  - Query Parameters:\n    - `bbox` (optional): Bounding box filter (minLon,minLat,maxLon,maxLat)\n    - `limit` (optional): Maximum number of features to return (1-1000)\n    - `offset` (optional): Starting offset for pagination\n  - Response: GeoJSON FeatureCollection\n\n### Authentication\n- `POST /auth/nonce`\n  - Request body: `{\"address\": \"0x...\"}`\n  - Returns a nonce for Web3 sign-in\n\n- `POST /auth/verify`\n  - Request body:\n    ```json\n    {\n      \"address\": \"0x...\",\n      \"signature\": \"0x...\",\n      \"nonce\": \"...\"\n    }\n    ```\n  - Returns a JWT token upon successful verification\n\n## Requirements\n\n- Python 3.11+\n- PostgreSQL with PostGIS extension\n- Poetry for dependency management\n\n## Quick Start\n\n1. Clone the repository:\n   ```bash\n   git clone git@github.com:AstralProtocol/api.git\n   cd astral-api\n   ```\n\n2. Install Poetry (if not already installed):\n   ```bash\n   curl -sSL https://install.python-poetry.org | python3 -\n   ```\n\n3. Install dependencies:\n   ```bash\n   poetry install\n   ```\n\n4. Set up environment variables:\n   ```bash\n   cp .env.example .env.development\n   # Edit .env.development with your configuration\n   ```\n\n5. Start the development server:\n   ```bash\n   poetry run uvicorn app.main:app --reload\n   ```\n\nThe API will be available at `http://localhost:8000`. OpenAPI documentation can be accessed at `http://localhost:8000/docs`.\n\n## Development\n\n### Project Structure\n\n```\nproject-root/\n├── app/                           # Main application package\n│   ├── components/                # API routes by resource\n│   ├── models/                    # SQLAlchemy models\n│   ├── schemas/                   # Pydantic models\n│   ├── services/                  # Business logic\n│   └── utils/                     # Utility functions\n├── tests/                         # Test suite\n├── alembic/                       # Database migrations\n└── config/                        # Configuration\n```\n\n### Running Tests\n\n```bash\npoetry run pytest\n```\n\n### Code Quality\n\nWe use pre-commit hooks to maintain code quality:\n\n```bash\npoetry run pre-commit install\npoetry run pre-commit run --all-files\n```\n\n### Continuous Integration\n\nWe use GitHub Actions for continuous integration. The CI pipeline:\n- Runs on every push and pull request to the main branch\n- Sets up Python 3.11 and Poetry\n- Installs project dependencies\n- Runs pre-commit hooks (black, isort, flake8, mypy)\n- Executes test suite with pytest\n- Reports test coverage to Codecov\n\nStatus badges:\n[![CI](https://github.com/AstralProtocol/api/actions/workflows/ci.yml/badge.svg)](https://github.com/AstralProtocol/api/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/AstralProtocol/api/branch/main/graph/badge.svg)](https://codecov.io/gh/AstralProtocol/api)\n\n## Documentation\n\n- [Project Requirements Document](docs/prd.md)\n- [Technical Stack](docs/tech-stack.md)\n- [Schema Design](docs/schema-design.md)\n- [Implementation Plan](docs/implementation-plan.md)\n\n## Adding New Chains\n\nThe API supports multiple blockchain networks through the `chain` table in the database. To add new chains or update existing ones, use the `seed_chains.py` script:\n\n### Basic Usage\n\n```bash\n# Add default supported chains (if they don't exist)\ndocker-compose exec api python scripts/seed_chains.py\n\n# Add specific chain IDs\ndocker-compose exec api python scripts/seed_chains.py 137 56 43114\n\n# Force update all default chains (overwrites existing entries)\ndocker-compose exec api python scripts/seed_chains.py --all\n\n# Add chains with custom EAS endpoints\ndocker-compose exec api python scripts/seed_chains.py --eas-file=custom_eas_endpoints.json\n```\n\n### Custom EAS Endpoints\n\nTo add chains with custom EAS GraphQL endpoints, create a JSON file with the following format:\n\n```json\n{\n    \"1\": \"https://easscan.org/graphql\",\n    \"137\": \"https://polygon.easscan.org/graphql\",\n    \"43114\": \"https://avalanche.easscan.org/graphql\"\n}\n```\n\nWhere the keys are chain IDs and the values are the GraphQL endpoints.\n\n### Adding to Production\n\nWhen adding chains to a production database:\n\n1. Test the changes in a staging environment first\n2. Back up the database before making changes\n3. Run the script with specific chain IDs to minimize impact:\n   ```bash\n   docker-compose exec api python scripts/seed_chains.py 137 43114\n   ```\n4. Verify the changes by querying the database:\n   ```bash\n   docker-compose exec db psql -U postgres -d astral -c \"SELECT chain_id, name, chain FROM chain\"\n   ```\n\n## License\n\n[License details to be added]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastralprotocol%2Fapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fastralprotocol%2Fapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastralprotocol%2Fapi/lists"}