{"id":21995371,"url":"https://github.com/blinklabs-io/cardano-node-api","last_synced_at":"2025-04-30T17:29:04.550Z","repository":{"id":65933706,"uuid":"601844959","full_name":"blinklabs-io/cardano-node-api","owner":"blinklabs-io","description":"Multi-protocol API for interfacing with a local Cardano node","archived":false,"fork":false,"pushed_at":"2024-10-29T11:42:30.000Z","size":648,"stargazers_count":8,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-29T13:26:18.196Z","etag":null,"topics":["api","blockchain","cardano","go","golang","ouroboros","ouroboros-network"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blinklabs-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-15T00:11:06.000Z","updated_at":"2024-10-29T11:42:32.000Z","dependencies_parsed_at":"2024-03-30T16:23:09.478Z","dependency_job_id":"b23f9311-8033-4800-981e-d6b3b0f793b4","html_url":"https://github.com/blinklabs-io/cardano-node-api","commit_stats":{"total_commits":154,"total_committers":6,"mean_commits":"25.666666666666668","dds":"0.39610389610389607","last_synced_commit":"77fe1f5bb8a1b1f52272b93a394df25efb56ebe1"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blinklabs-io%2Fcardano-node-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blinklabs-io%2Fcardano-node-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blinklabs-io%2Fcardano-node-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blinklabs-io%2Fcardano-node-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blinklabs-io","download_url":"https://codeload.github.com/blinklabs-io/cardano-node-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227215003,"owners_count":17748961,"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":["api","blockchain","cardano","go","golang","ouroboros","ouroboros-network"],"created_at":"2024-11-29T21:14:37.597Z","updated_at":"2025-04-30T17:29:04.538Z","avatar_url":"https://github.com/blinklabs-io.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cardano-node-api\n\nCardano Node API\n\nAn HTTP API for interfacing with a local Cardano Node and providing the node\ninternal data for HTTP clients. This service communicates with a Cardano\nfull node using the Ouroboros network protocol via a UNIX socket and exposes\nthe underlying Node-to-Client (NtC) Ouroboros mini-protocols to clients via\na REST API or UTxO RPC gRPC API.\n\n## Usage\n\nThe recommended method of using this application is via the published\ncontainer images, coupled with Blink Labs container images for the Cardano\nNode.\n\n```\ndocker run -d \\\n  -p 8080:8080 \\\n  -p 9090:9090 \\\n  -v \u003cmount for cardano-node IPC\u003e \\\n  ghcr.io/blinklabs-io/cardano-node-api:main\n```\n\n\u003c!-- Binaries can be executed directly and are available from\n[Releases](https://github.com/blinklabs-io/cardano-node-api/releases).\n\n```\n./cardano-node-api\n```\n--\u003e\n### Configuration\n\nConfiguration can be done using either a `config.yaml` file or setting\nenvironment variables. Our recommendation is environment variables to adhere\nto the 12-factor application philisophy.\n\n#### Environment variables\n\nConfiguration via environment variables can be broken into two sets of\nvariables. The first set controls the behavior of the application, while the\nsecond set controls the connection to the Cardano node instance.\n\nApplication configuration:\n- `API_LISTEN_ADDRESS` - Address to bind for API calls, all addresses if empty\n    (default: empty)\n- `API_LISTEN_PORT` - Port to bind for API calls (default: 8080)\n- `DEBUG_ADDRESS` - Address to bind for pprof debugging (default: localhost)\n- `DEBUG_PORT` - Port to bind for pprof debugging, disabled if 0 (default: 0)\n- `GRPC_LISTEN_ADDRESS` - Address to bind for UTxO RPC gRPC, all addresses if empty\n    (default: empty)\n- `GRPC_LISTEN_PORT` - Port to bind for gRPC calls (default: 9090)\n- `LOGGING_HEALTHCHECKS` - Log requests to `/healthcheck` endpoint (default: false)\n- `LOGGING_LEVEL` - Logging level for log output (default: info)\n- `METRICS_LISTEN_ADDRESS` - Address to bind for Prometheus format metrics, all\n    addresses if empty (default: empty)\n- `METRICS_LISTEN_PORT` - Port to bind for metrics (default: 8081)\n- `TLS_CERT_FILE_PATH` - SSL certificate to use, requires `TLS_KEY_FILE_PATH`\n    (default: empty)\n- `TLS_KEY_FILE_PATH` - SSL certificate key to use (default: empty)\n\nConfiguring the TLS certificate and key paths will enable TLS on both the REST\nAPI and the gRPC interface.\n\nConnection to the Cardano node can be performed using specific named network\nshortcuts for known network magic configurations. Supported named networks are:\n\n- mainnet\n- preprod\n- preview\n- sanchonet\n\nYou can set the network to an empty value and provide your own network magic to\nconnect to unlisted networks.\n\nTCP connection to a Cardano Node without using an intermediary like SOCAT is\npossible using the node address and port. It is up to you to expose the node's\nNtC communication socket over TCP. TCP connections are preferred over socket\nwithin the application.\n\nCardano node configuration:\n- `CARDANO_NETWORK` - Use a named Cardano network (default: mainnet)\n- `CARDANO_NODE_NETWORK_MAGIC` - Cardano network magic (default: automatically\n    determined from named network)\n- `CARDANO_NODE_SKIP_CHECK` - Skip the connection test to Cardano Node on start\n    (default: false)\n- `CARDANO_NODE_SOCKET_PATH` - Socket path to Cardano node NtC via UNIX socket\n    (default: /node-ipc/node.socket)\n- `CARDANO_NODE_SOCKET_TCP_HOST` - Address to Cardano node NtC via TCP\n   (default: unset)\n- `CARDANO_NODE_SOCKET_TCP_PORT` - Port to Cardano node NtC via TCP (default:\n    unset)\n- `CARDANO_NODE_SOCKET_TIMEOUT` - Sets a timeout in seconds for waiting on\n   requests to the Cardano node (default: 30)\n\n### Connecting to a cardano-node\n\nYou can connect to either a cardano-node running locally on the host or a\ncontainer running either `inputoutput/cardano-node` or\n`ghcr.io/blinklabs-io/cardano-node` by mapping in the correct paths and setting\nthe environment variables or configuration options to match.\n\n#### Together with ghcr.io/blinklabs-io/cardano-node in Docker\n\nUse Docker to run both cardano-node and cardano-node-api with Docker\nvolumes for blockchain storage and node-ipc.\n\n```\n# Start mainnet node\ndocker run --detach \\\n  --name cardano-node \\\n  -v node-data:/opt/cardano/data \\\n  -v node-ipc:/opt/cardano/ipc \\\n  -p 3001:3001 \\\n  ghcr.io/blinklabs-io/cardano-node run\n\n# Start cardano-node-api\ndocker run --detach \\\n  --name cardano-node-api \\\n  -v node-ipc:/node-ipc \\\n  -p 8080:8080 \\\n  -p 9090:9090 \\\n  ghcr.io/blinklabs-io/cardano-node-api:main\n```\n\n#### Using a local cardano-node\n\nUse the local path when mapping the node-ipc volume into the container to use\na local cardano-node.\n\n```\n# Start cardano-node-api\ndocker run --detach \\\n  --name cardano-node-api \\\n  -v /opt/cardano/ipc:/node-ipc \\\n  -p 8080:8080 \\\n  -p 9090:9090 \\\n  ghcr.io/blinklabs-io/cardano-node-api:main\n```\n\n## Development\n\nThere is a Makefile to provide some simple helpers.\n\nRun from checkout:\n```\ngo run .\n```\n\nCreate a binary:\n```\nmake\n```\n\nCreate a docker image:\n```\nmake image\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblinklabs-io%2Fcardano-node-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblinklabs-io%2Fcardano-node-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblinklabs-io%2Fcardano-node-api/lists"}