{"id":44917695,"url":"https://github.com/txpipe/assets-api-starter-kit","last_synced_at":"2026-02-18T02:36:26.793Z","repository":{"id":64860835,"uuid":"576663642","full_name":"txpipe/assets-api-starter-kit","owner":"txpipe","description":"A Demeter Starter Kit showing how to create a REST API to query asset data from DB-Sync","archived":false,"fork":false,"pushed_at":"2022-12-16T12:57:22.000Z","size":2413,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2023-08-20T09:01:52.586Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/txpipe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-12-10T15:21:53.000Z","updated_at":"2023-08-20T09:01:52.586Z","dependencies_parsed_at":"2022-12-16T22:48:21.520Z","dependency_job_id":null,"html_url":"https://github.com/txpipe/assets-api-starter-kit","commit_stats":null,"previous_names":[],"tags_count":0,"template":null,"template_full_name":null,"purl":"pkg:github/txpipe/assets-api-starter-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txpipe%2Fassets-api-starter-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txpipe%2Fassets-api-starter-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txpipe%2Fassets-api-starter-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txpipe%2Fassets-api-starter-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/txpipe","download_url":"https://codeload.github.com/txpipe/assets-api-starter-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txpipe%2Fassets-api-starter-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29566410,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T00:47:08.760Z","status":"online","status_checked_at":"2026-02-18T02:00:09.468Z","response_time":162,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":"2026-02-18T02:36:26.735Z","updated_at":"2026-02-18T02:36:26.786Z","avatar_url":"https://github.com/txpipe.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Assets API Starter Kit\n\nThis starter kit shows how you can start building a simple REST API to query assets data from [DB-sync](https://docs.cardano.org/cardano-components/cardano-db-sync/about-db-sync).\n\n## Dev Environment\n\nFor executing this starter kit you'll need access to a running [DB-sync](https://docs.cardano.org/cardano-components/cardano-db-sync/about-db-sync) instance in sync with a Node running on the network of your preference.\n\nIn case you don't want to install the required components yourself, you can use [Demeter.run](https://demeter.run) platform to create a cloud environment with access to common Cardano infrastructure. The following command will open this repo in a private, web-based VSCode IDE with access to a running DB-Sync instance in the preview network.\n\n[![Code in Cardano Workspace](https://demeter.run/code/badge.svg)](https://demeter.run/code?repository=https://github.com/txpipe/assets-api-starter-kit\u0026template=typescript)\n\n### Implementation Details\n\nThis Starter Kit implements a very simple REST API with a single GET endpoint for querying Assets information for a given `Policy Id`. \n\nThe server is a [NodeJs](https://nodejs.org/en/) application using [ExpressJS](https://expressjs.com/) and Typescript. \n\nWe have implemented the API following the clean architecture principles, making it easy to include new endpoints, data sources and use cases. \n\nFor connecting with the database layer we have chosen to use [Prisma](https://www.prisma.io/) which provides us with a great development experience when it comes to access and querying db-sync. \n\n\u003cimg src=\"/assets/diagram.png\" alt=\"diagram\"\u003e\n\n### Building \u0026 Running the Application\n\nFrom the web-based workspace open a new Terminal and run the following commands for installing the dependencies:\n\n```bash\n$ npm install\n```\n\nNext we need to get Prisma initialized and connected against our db-sync instance. \n```bash\nnpx prisma init\n```\n\nNow we should have 2 new files generated in our repository:\n\n* `prisma.schema`\n* `.env`\n\nIf you open `prisma.schema` you will notice the schema is empty:\n```typescript\n// This is your Prisma schema file,\n// learn more about it in the docs: https://pris.ly/d/prisma-schema\n\ngenerator client {\n  provider = \"prisma-client-js\"\n}\n\ndatasource db {\n  provider = \"postgresql\"\n  url      = env(\"DATABASE_URL\")\n}\n```\n\nFor pulling the db-sync schema we are going to use the [Demeter.run](https://demeter.run) DB-Sync feature. \n\nOpen your project Console in [Demeter.run](https://demeter.run) and go to the DB-Sync feature from the list.\n\n\u003cimg src=\"assets/console-features.png\" alt=\"db-sync features\"\u003e\n\nGo into the feature detail and copy the value of the `Connection string` field. \n\n\u003cimg src=\"assets/db-sync-settings.png\" alt=\"db-sync settings\"\u003e\n\n\nYou can now replace the content of the `DATABASE_URL` variable in the `.env` file generated by `npx prisma init` with this information:\n\n```bash\n# Environment variables declared in this file are automatically made available to Prisma.\n# See the documentation for more detail: https://pris.ly/d/prisma-schema#accessing-environment-variables-from-the-schema\n\n# Prisma supports the native connection string format for PostgreSQL, MySQL, SQLite, SQL Server, MongoDB and CockroachDB.\n# See the documentation for all the connection string options: https://pris.ly/d/connection-strings\n\nDATABASE_URL=\"postgresql://dmtrro:ZC0LwSZJnBZo60yOKoBIL0zjAIFt6OPTTiWRyZ6LZsWfZGn4Z2OGH6WW844GMVr8@dmtr-preview-postgres-repl.ftr-dbsync-v1.svc.cluster.local:5432/cardanodbsync?schema=public\"\n```\n\nOnce the `.env` file is updated go back to the terminal and run the following command:\n\n```bash\nnpx prisma db pull\nnpx prisma generate\n```\n\nThis command should have generated the high level Typescript objects for accessing DB-Sync from our code. \nIf you check the `prisma.schema` file again you should see its now updated with the schema definition of db-sync. \n\n```typescript\ngenerator client {\n  provider = \"prisma-client-js\"\n}\n\ndatasource db {\n  provider = \"postgresql\"\n  url      = env(\"DATABASE_URL\")\n}\n\nmodel ada_pots {\n  id       BigInt  @id @default(autoincrement())\n  slot_no  BigInt\n  epoch_no Int\n  treasury Decimal @db.Decimal(20, 0)\n  reserves Decimal @db.Decimal(20, 0)\n  rewards  Decimal @db.Decimal(20, 0)\n  utxo     Decimal @db.Decimal(20, 0)\n  deposits Decimal @db.Decimal(20, 0)\n  fees     Decimal @db.Decimal(20, 0)\n  block_id BigInt  @unique(map: \"unique_ada_pots\")\n  block    block   @relation(fields: [block_id], references: [id], onDelete: Cascade, onUpdate: Restrict)\n} ...\n```\n\nFeel free to explore the schema from this file, or you can use the `Schema` tab inside of the `DB-Sync` feature of [Demeter.run](https://demeter.run) for browsing the available tables. \n\n\u003cimg src=\"assets/db-sync-schema.png\" alt=\"db-sync schema\"\u003e\n\nFor our REST API we have implemented a data source in `assetsDataSource.ts`. You can check `DBSyncAssetsDataSource` for how we are using Prisma for querying DB-Sync and returning the Assets information mapped to a high-level object:\n\n```typescript\nasync getForPolicyId(policyId: string): Promise\u003cAsset[]\u003e {\n    const multiAssets = await this.client.multi_asset.findMany({\n        where: {\n            policy: Buffer.from(policyId, 'hex'),\n        },\n        include: {\n            ma_tx_mint: true,\n        }\n    });\n    return multiAssets.map((m) =\u003e {\n        const asset = mapAsset(m);\n        m.ma_tx_mint.forEach((t) =\u003e {\n            asset.quantity += t.quantity.toNumber();\n        });\n        return asset;\n    });\n}\n```\n\n#### Build and Run\n\nOnce we have Prisma connected to our DB-Sync instance we can build and run the application. Go back to the terminal and execute the following commands:\n\n```bash\nnpm run build\nnpm run dev\n```\n\nYour application should be now running in localhost:8000\n\n### Testing the Application\n\nIf you want to test your API from outside of the workspace environment we need to expose the workspace port where the application is running.\n\nFor doing this in the [Demeter.run](https://demeter.run) console go to your workspaces, select the workspace where you are running the starter kit and go to the Exposed Ports tab. \n\nFrom this tab you can select to expose a new port. \n\n\u003cimg src=\"/assets/assets-api-expose-port.png\" alt=\"expose-port-new\"\u003e\n\nOnce your port is exposed you can try a GET request to the auto-generated URL from your web browser\n\n\u003cimg src=\"/assets/assets-api-exposed-ports.png\" alt=\"expose-port-list\"\u003e\n\nExample request with a policy id from the `preview` network:\n\n```bash \nhttps://8000-slippery-sympathy-7n7uxh.us1.demeter.run/assets/policy/f5335f99c169cf2cbec9c6405750b533c011b24705590b800aa54cd6\n```\n\nThe response we get for the given policy id:\n```json\n[{\n\t\"id\": \"118\",\n\t\"fingerprint\": \"asset1uxw6angvk9tvaa79u98xw44tcqf6hflur3jr34\",\n\t\"name\": \"HOSKYt_Spectrum_Lq\",\n\t\"policyId\": \"f5335f99c169cf2cbec9c6405750b533c011b24705590b800aa54cd6\",\n\t\"quantity\": 9223372036854776000\n}]\n```\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftxpipe%2Fassets-api-starter-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftxpipe%2Fassets-api-starter-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftxpipe%2Fassets-api-starter-kit/lists"}