{"id":26524967,"url":"https://github.com/hypercerts-org/hypercerts-api","last_synced_at":"2025-06-27T03:36:48.762Z","repository":{"id":215523814,"uuid":"738996439","full_name":"hypercerts-org/hypercerts-api","owner":"hypercerts-org","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-24T17:40:54.000Z","size":1483,"stargazers_count":1,"open_issues_count":33,"forks_count":1,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-06-24T18:43:44.823Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://hypercerts-api.vercel.app","language":"TypeScript","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/hypercerts-org.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-01-04T14:32:57.000Z","updated_at":"2025-06-24T17:41:06.000Z","dependencies_parsed_at":"2024-01-15T14:11:10.672Z","dependency_job_id":"4048cfbf-2ce2-481c-8d71-50cce420de63","html_url":"https://github.com/hypercerts-org/hypercerts-api","commit_stats":null,"previous_names":["hypercerts-org/hypercerts-api"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hypercerts-org/hypercerts-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypercerts-org%2Fhypercerts-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypercerts-org%2Fhypercerts-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypercerts-org%2Fhypercerts-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypercerts-org%2Fhypercerts-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hypercerts-org","download_url":"https://codeload.github.com/hypercerts-org/hypercerts-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypercerts-org%2Fhypercerts-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262182781,"owners_count":23271684,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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-03-21T14:39:51.521Z","updated_at":"2025-06-27T03:36:48.743Z","avatar_url":"https://github.com/hypercerts-org.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hypercerts API\n\nThe hypercerts API is the touchpoint for developers to interact with the hypercerts ecosystem. It provides endpoints for data upload and fetching, a GraphQL API for querying (on-chain) state and a health check endpoint.\n\n## Getting started\n\n### Environment variables\n\n#### W3UP\n\nIn `env.template` you'll find KEY and PROOF which are [w3up](https://web3.storage/docs/w3up-client/) key and proofs which you need to set up yourself for local otherwise you'll be superadmin 😉\n\n#### Supabase JS\n\nSupabaseJS is used to connect to both the the caching and data service. The local variables are deterministic and provided in the template.\n\n#### Kysely\n\nKysely is implemented in favor of SupabaseJS as it allows for more flexibility and complexity in queries. To connect to the database you need to set the `CACHING_DATABASE_URL` and `DATA_DATABASE_URL` in the `.env` file. By default, the local variables are set to the local Supabase instance.\n\n#### Sentry\n\nSentry is used for monitoring and error reporting. You can read more about it [here](https://docs.sentry.io/platforms/javascript/guides/node/configuration/env-vars/). When Sentry is set to `local` it will be disabled by default.\n\n#### RPCs\n\nThe API implements a fallback to the first available RPC. You can set the RPCs in the `.env` file.\n\n### Supabase\n\n- Install Docker\n- `git submodule init`\n- `git submodule update --remote`\n- `pnpm supabase:start:all`\n\nThis will spin up 2 Supabase instances in Docker, one for the indexer service (caching) and one for the data service (static data) which are both exposed by the API.\n\nFrom both instances, you can get their respective keys and add them to the env vars. When in doubt you can run `supabase status` to fetch the keys again. By default this is not needed for local development.\n\n### Run the API locally\n\n`pnpm dev`\n\nThis will run a live production instance by running `swc` to compile the code and `nodemon` to restart the server on changes.\n\nYou can then find the API at `localhost:4000/spec` (Swagger instance) and the GraphQL at `localhost:4000/v2/graphql`\n\n## Deployments\n\nProduction: `https://api.hypercerts.org/`\nStaging: `https://staging-api.hypercerts.org`\n\n`/spec` - Swagger instance documenting the API and exposing a playground to experiment with the endpoints\n`/v2/graphql` - GraphQL API to access hypercerts data like claims, fractions, attestations, allow lists\n\n## Scripts\n\n- `dev`: Starts the development server using `nodemon`, which will automatically restart the server whenever you save a file that the server uses.\n- `build`: Denerates the OpenAPI specification and routes using `tsoa`, and then compiles the TypeScript code into JavaScript using `swc`. The compiled code is output to the `dist` directory.\n- `start`: Starts the application in production mode.\n- `lint`: Runs `eslint` on the codebase to check for linting errors.\n- `test`: Runs tests using `vitest`\n\n## Data\n\nThe API service exposes data from two sources:\n\n- The static data service which contains off-chain data like user data, hypercert collections, signed order messages, etc.\n- The indexer service which contains on-chain data about hypercerts and the linked data on IPFS (hypercerts, ownerships, metadata, attestations, etc.)\n\n### Static data service\n\nThe static data service is a Supabase database which is exposed by the API. This means that you can create, update and delete data through the API. For read functionality we recommend using the GraphQL API and playground to carefully compose the data model needed for your use case.\n\n### Indexer service\n\nThe indexer service monitors our supported chains for relevant events and handles those events accordingly. All data exposed by the indexer service is available in different sources as well, like IPFS for metadata and EAS for attestations.\n\n## Validations\n\nThe API also provides an upload and validation endpoint for hypercert and allow list data. In the [live docs](https://api.hypercerts.org/spec) you can find the endpoint and docs. Generally, by using `validate` you can post the data for validation without it being uploaded to IPFS.\n\n## Architecture\n\n```mermaid\ngraph TB\n    Client[Client Applications]\n    API[Hypercerts API :4000]\n\n    subgraph \"API Endpoints\"\n        Swagger[\"/spec\\nSwagger Documentation\"]\n        GraphQL[\"/v2/graphql\\nGraphQL Endpoint\"]\n        Upload[\"Upload \u0026 Validation\\nEndpoints\"]\n    end\n\n    subgraph \"Data Services\"\n        Static[(\"Static Data Service\\n(Supabase DB)\\n- User Data\\n- Collections\\n- Signed Orders\")]\n        Indexer[(\"Indexer Service\\n(Supabase DB)\\n- On-chain Data\\n- IPFS Data\")]\n    end\n\n    subgraph \"External Services\"\n        IPFS[(IPFS\\nMetadata Storage)]\n        Blockchain[(Blockchain\\nSupported Chains)]\n        EAS[(EAS\\nAttestations)]\n    end\n\n    Client --\u003e API\n    API --\u003e Swagger\n    API --\u003e GraphQL\n    API --\u003e Upload\n\n    GraphQL --\u003e Static\n    GraphQL --\u003e Indexer\n    Upload --\u003e IPFS\n\n    Indexer --\u003e Blockchain\n    Indexer --\u003e IPFS\n    Indexer --\u003e EAS\n\n    class Swagger,GraphQL,Upload apiEndpoint;\n    class Static,Indexer database;\n    class IPFS,Blockchain,EAS external;\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypercerts-org%2Fhypercerts-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhypercerts-org%2Fhypercerts-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypercerts-org%2Fhypercerts-api/lists"}