github.com/howijd/koios-rest-go-client
:warning: UNTIL v1.0.0 RELEASE THIS LIBRARY WILL GET BREAKING CHANGES :warning:
v0.x.x MINOR semver update most likely has breaking change.go get -u check for changes to prevent inconveniences.v1.0.0 enhancements are tracked under following issueKoios API is Elastic Cardano Query Layer!
A consistent query layer for developers to build upon Cardano, with
multiple, redundant endpoints that allow for easy scalability.
Koios API Client Library for Go
go get github.com/howijd/koios-rest-go-client
...
import (
"github.com/howijd/koios-rest-go-client" // imports as package "koios"
)
...
CLI Application to interact with Koios API from Command-line see
Build Status
Development Status
See Godoc
Additionally you can find all usecases by looking source of
koio-rest Command-line application source which utilizes entire API of this library.
NOTE
Library normalizes some of the API responses and constructs Typed response for each end point.
If you wish to work with *http.Response directly you can do so by using api client GET,POST, HEAD methods.
package main
import (
"context"
"fmt"
"log"
koios "github.com/howijd/koios-rest-go-client"
)
func main() {
// Call to koios.New without options is same as calling it with default opts.
// See godoc for available configuration options.
// api, err := koios.New(
// koios.Host(koios.MainnetHost),
// koios.APIVersion(koios.DefaultAPIVersion),
// koios.Port(koios.DefaultPort),
// koios.Schema(koios.DefaultSchema),
// koios.HttpClient(koios.DefaultHttpClient),
// ).
api, err := koios.New()
if err != nil {
log.Fatal(err)
}
res, err := api.GetTip(context.Background())
if err != nil {
log.Fatal(err)
}
fmt.Println("status: ", res.Status)
fmt.Println("statu_code: ", res.StatusCode)
fmt.Println("abs_slot: ", res.Data.AbsSlot)
fmt.Println("block_no: ", res.Data.BlockNo)
fmt.Println("block_time: ", res.Data.BlockTime)
fmt.Println("epoch: ", res.Data.Epoch)
fmt.Println("epoch_slot: ", res.Data.EpochSlot)
fmt.Println("hash: ", res.Data.Hash)
}
This library is thread-safe so you can freerly use same api client instance passing it to your goroutines.
Following example uses goroutines to query chain tip from different endpoints.
func main() {
api, _ := koios.New(
// limit client request 1 per second even though
// this example will send requests in goroutines.
koios.RateLimit(1),
)
ctx := context.Background()
var wg sync.WaitGroup
servers := []string{
"api.koios.rest",
"guild.koios.rest",
"testnet.koios.rest",
}
// Thanks to rate limit option requests will be made
// once in a second.
for _, host := range servers {
wg.Add(1)
go func(ctx context.Context, host string) {
defer wg.Done()
// switching host. all options changes are safe to call from goroutines.
koios.Host(host)(api)
res, _ := api.GET(ctx, "/tip", nil, nil)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println("Host: ", host)
fmt.Println("Response: ", string(body))
}(ctx, host)
}
wg.Wait()
fmt.Println("requests done: ", api.TotalRequests())
}
Library uses for most cases to represent lovelace using Lovelace data type.
This library uses forked snapshot of github.com/shopspring/decimal package to provide
JSON and XML serialization/deserialization and make it ease to work with calculations
and deciimal precisions of ADA lovelace and native assets.
For decimal package API see
FORK: https://github.com/howijd/decimal
issues and bug reports are welcome to: https://github.com/howijd/decimal/issue.
So that we can ensure that github.com/shopspring/decimal repository is not polluted with
issues which are not problems with upstream library.
source of cli: ./cmd/koios-rest.
koios-rest --helpNAME:
koios-rest - CLI Client to consume Koios API https://api.koios.rest
USAGE:
koios-rest [global options] command [command options] [arguments...]
VERSION:
(devel)
AUTHOR:
The Howijd.Network Authors
COMMANDS:
help, h Shows a list of commands or help for one command
ACCOUNT:
account-list Get a list of all accounts returns array of stake addresses.
account-info Get the account info of any (payment or staking) address.
account-rewards Get the full rewards history (including MIR) for a stake address, or certain epoch if specified.
account-updates Get the account updates (registration, deregistration, delegation and withdrawals).
account-addresses Get all addresses associated with an account payment or staking address
account-assets Get the native asset balance of an account.
account-history Get the staking history of an account.
ADDRESS:
address-info Get address info - balance, associated stake address (if any) and UTxO set.
address-txs Get the transaction hash list of input address array, optionally filtering after specified block height (inclusive).
address-assets Get the list of all the assets (policy, name and quantity) for a given address.
credential-txs Get the transaction hash list of input payment credential array, optionally filtering after specified block height (inclusive).
ASSET:
asset-list Get the list of all native assets (paginated).
asset-address-list Get the list of all addresses holding a given asset.
asset-info Get the information of an asset including first minting & token registry metadata.
asset-summary Get the summary of an asset (total transactions exclude minting/total wallets include only wallets with asset balance).
asset-txs Get the list of all asset transaction hashes (newest first).
BLOCK:
blocks Get summarised details about all blocks (paginated - latest first).
block-info Get detailed information about a specific block.
block-txs Get a list of all transactions included in a provided block.
EPOCH:
epoch-info Get the epoch information, all epochs if no epoch specified.
epoch-params Get the protocol parameters for specific epoch, returns information about all epochs if no epoch specified.
NETWORK:
tip Get the tip info about the latest block seen by chain.
genesis Get the Genesis parameters used to start specific era on chain.
totals Get the circulating utxo, treasury, rewards, supply and reserves in lovelace for specified epoch, all epochs if empty.
POOL:
pool-list A list of all currently registered/retiring (not retired) pools.
pool-infos Current pool statuses and details for a specified list of pool ids.
pool-info Current pool status and details for a specified pool by pool id.
pool-delegators Return information about delegators by a given pool and optional epoch (current if omitted).
pool-blocks Return information about blocks minted by a given pool in current epoch (or _epoch_no if provided).
pool-updates Return all pool updates for all pools or only updates for specific pool if specified.
pool-relays A list of registered relays for all currently registered/retiring (not retired) pools.
pool-metadata Metadata(on & off-chain) for all currently registered/retiring (not retired) pools.
SCRIPT:
script-list List of all existing script hashes along with their creation transaction hashes.
script-redeemers List of all redeemers for a given script hash.
TRANSACTIONS:
txs-infos Get detailed information about transaction(s).
tx-info Get detailed information about single transaction.
tx-utxos Get UTxO set (inputs/outputs) of transactions.
txs-metadata Get metadata information (if any) for given transaction(s).
tx-metadata Get metadata information (if any) for given transaction.
tx-metalabels Get a list of all transaction metalabels.
tx-submit Submit signed transaction to the network.
txs-statuses Get the number of block confirmations for a given transaction hash list
tx-status Get the number of block confirmations for a given transaction hash
UTILS:
get get issues a GET request to the specified API endpoint
head head issues a HEAD request to the specified API endpoint
GLOBAL OPTIONS:
--port value, -p value Set port (default: 443)
--host value Set host (default: "api.koios.rest")
--api-version value Set API version (default: "v0")
--schema value Set URL schema (default: "https")
--origin value Set Origin header for requests. (default: "https://github.com/howijd/koios-rest-go-client")
--rate-limit value Set API Client rate limit for outgoing requests (default: 5)
--no-format prints response json strings directly without calling json pretty. (default: false)
--enable-req-stats Enable request stats. (default: false)
--testnet use default testnet as host. (default: false)
--help, -h show help (default: false)
--version, -v print the version (default: false)
COPYRIGHT:
(c) 2022
koios-rest --enable-req-stats tip
response
{
"request_url": "https://api.koios.rest/api/v0/tip",
"request_method": "GET",
"status_code": 200,
"status": "200 OK",
"date": "Mon, 07 Feb 2022 12:49:49 GMT",
"content_range": "0-0/*",
"stats": {
"req_started_at": "2022-02-07T12:49:48.565834833Z",
"req_dns_lookup_dur": 1284269, // dns lookup duration in nanosecons.
"tls_hs_dur": 208809082, // handshake duration in nanosecons.
"est_cxn_dur": 159857626, // time it took to establish connection with server in nanosecons.
"ttfb": 998874037, // time since start of the request it took to recieve first byte.
"req_dur": 999186595, // total request duration in nanoseconds
"req_dur_str": "999.186595ms" // string of req_dur
},
"data": {
"abs_slot": 52671876,
"block_no": 6852764,
"block_time": "2022-02-07T12:49:27",
"epoch": 319,
"epoch_slot": 227076,
"hash": "1dad134750188460dd48068e655b5935403d2f51afaf53a39337a4c89771754a"
}
koios-rest --enable-req-stats --testnet tip
# OR
koios-rest --enable-req-stats --host testnet.koios.rest tip
response
{
"request_url": "https://testnet.koios.rest/api/v0/tip",
"request_method": "GET",
"status_code": 200,
"status": "200 OK",
"date": "Mon, 07 Feb 2022 12:50:04 GMT",
"content_range": "0-0/*",
"stats": {
"req_started_at": "2022-02-07T12:50:03.98615637Z",
"req_dns_lookup_dur": 1383437,
"tls_hs_dur": 69093093,
"est_cxn_dur": 43733700,
"ttfb": 167423049,
"req_dur": 167738287,
"req_dur_str": "167.738287ms"
},
"data": {
"abs_slot": 49868948,
"block_no": 3300758,
"block_time": "2022-02-07T12:49:24",
"epoch": 185,
"epoch_slot": 318548,
"hash": "d7623e68cb78f450f42ba4b5a169124b26677f08f676ca4241b27edb6dbf0071"
}
}
It's highly recommended installing a latest version of koios-rest available on the releases page.
Installing from source requires a working Go environment. See the install instructions for Go.
Since koios-rest cli application uses replace in ./cmd/koiso-rest/go.mod.
Then go install won't work. To install it from source use following commands.
git clone git@github.com:howijd/koios-rest-go-client.gitcd ./koios-rest-go-client/cmd/koios-restgo install .verify installation
koios-rest --version
We would love for you to contribute to Koios API Client Library for Go and help make it even better than it is today! As a contributor, here are the guidelines we would like you to follow:
Help us keep Koios API Client Library for Go open and inclusive. Please read and follow our [Code of Conduct][code-of-conduc]
Do not open issues for general support questions as we want to keep GitHub issues for bug reports and feature requests. You've got much better chances of getting your question answered on Koios Telegram Group
If you find a bug in the source code, you can help us by submitting an issue to our GitHub Repository. Even better, you can submit a Pull Request with a fix.
You can request a new feature by submitting an issue to our GitHub Repository. If you would like to implement a new feature, please submit an issue with a proposal for your work first, to be sure that we can use it. Please consider what kind of change it is:
Before you submit an issue, please search the issue tracker, maybe an issue for your problem already exists and the discussion might inform you of workarounds readily available.
You can file new issues by filling out our new issue form.
Before you submit your Pull Request (PR) consider the following guidelines:
Search GitHub for an open or closed PR that relates to your submission. You don't want to duplicate effort.
Fork the howijd/koios-rest-go-client repo.
Setup you local repository
git@github.com:<your-github-username>/koios-rest-go-client.git
cd koios-rest-go-client
git remote add upstream git@github.com:howijd/koios-rest-go-client.git
Make your changes in a new git branch and ensure that you always start from up to date main branch. Repeat this step every time you are about to start woking on new PR.
e.g. Start new change work to update readme:
# if you are not in main branch e.g. still on previous work branch
git checkout main
git pull --ff upstream main
git checkout -b update-readme main
Create your patch, including appropriate test cases.
Follow our Coding Rules.
If changes are in source code except documentations then run the full test suite, as described in the developer documentation, and ensure that all tests pass.
Commit your changes using a descriptive commit message that follows our commit message conventions. Adherence to these conventions is necessary because release notes are automatically generated from these messages.
git add -A
git commit --signoff
# or in short
git commit -sm"docs(markdown): update readme examples"
Push your branch to GitHub:
git push -u origin update-readme
In GitHub, send a pull request to main branch.
Make the required updates.
Re-run the test suites to ensure tests are still passing.
Rebase your branch and force push to your GitHub repository (this will update your Pull Request):
git fetch --all
git rebase upstream main
git push -uf origin update-readme
That's it! Thank you for your contribution!
After your pull request is merged, you can safely delete your branch and pull the changes from the main (upstream) repository:
Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:
git push origin --delete update-readme
Check out the main branch:
git checkout main -f
Delete the local branch:
git branch -D update-readme
Update your master with the latest upstream version:
git pull --ff upstream main
To ensure consistency throughout the source code, keep these rules in mind as you are working:
We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history. Commit messages should be well formatted, and to make that "standardized", we are using Conventional Commits. Our release workflow uses these rules to generate changelogs.
Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
When maintainers are merging PR merge commit should be edited:
<type>(<scope>): <subject> (#pr)
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
The header is mandatory and the scope of the header is optional.
Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.
The footer should contain a closing reference to an issue if any.
Samples:
docs(markdown): update readme examples
fix(cli): fix cli command get action
description of your change.
refactor(client): change Client GET function signature
change order of client GET method arguments.
BREAKING CHANGE: Clien.Get signature has changed
If the commit reverts a previous commit, it should begin with revert: , followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.
Must be one of the following:
go.modThe following is the list of supported scopes:
| scope | description |
|---|---|
| cli | CLI app related changes |
| client | API client related changes |
| endpoint | Changes related to api endpoints |
| godoc | Go documentation |
| markdown | Markdown files |
| packaging | Used for changes that change the release packages |
The subject contains a succinct description of the change:
Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.
The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit Closes.
Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message is then used for this.
A detailed explanation can be found in this [document][commit-message-format].
Prerequisites:
Working Go environment. See the install instructions for Go.
golangci-lint - Go linters aggregator should be installed
taskfile - task runner / build tool should be installed
svu - Semantic Version Util tool should be installed
Fork the howijd/koios-rest-go-client repo.
Setup you local repository
git@github.com:<your-github-username>/koios-rest-go-client.git
cd koios-rest-go-client
git remote add upstream git@github.com:howijd/koios-rest-go-client.git
Setup local env
task setup
Lint your code
task lint
Test your change
task test
View code coverage report from in browser (results from task test)
task cover
Build snapshot binaries to ./cmd/koios-rest/dist.
use it if you want to test release packages
task build:snapshot
FAQs
Unknown package
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
License exceptions modify the terms of open source licenses, impacting how software can be used, modified, and distributed. Developers should be aware of the legal implications of these exceptions.
Security News
A developer is accusing Tencent of violating the GPL by modifying a Python utility and changing its license to BSD, highlighting the importance of copyleft compliance.
Security News
In an open letter, JavaScript community leaders urge Oracle to give up the JavaScript trademark, arguing that it has been effectively abandoned through nonuse.