{"id":13810962,"url":"https://github.com/kinecosystem/kin-node","last_synced_at":"2025-05-14T15:31:26.070Z","repository":{"id":41845503,"uuid":"288241739","full_name":"kinecosystem/kin-node","owner":"kinecosystem","description":"DEPRECATED! Please use Kinetic: https://developer.kin.org/docs/kinetic","archived":true,"fork":false,"pushed_at":"2022-11-21T19:00:25.000Z","size":577,"stargazers_count":16,"open_issues_count":7,"forks_count":14,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-12-20T15:50:29.249Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://developer.kin.org/docs/kinetic","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/kinecosystem.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-08-17T17:20:25.000Z","updated_at":"2023-02-15T01:47:58.000Z","dependencies_parsed_at":"2022-08-11T19:10:57.863Z","dependency_job_id":null,"html_url":"https://github.com/kinecosystem/kin-node","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kinecosystem%2Fkin-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kinecosystem%2Fkin-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kinecosystem%2Fkin-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kinecosystem%2Fkin-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kinecosystem","download_url":"https://codeload.github.com/kinecosystem/kin-node/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254171812,"owners_count":22026523,"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":"2024-08-04T03:00:33.614Z","updated_at":"2025-05-14T15:31:21.058Z","avatar_url":"https://github.com/kinecosystem.png","language":"TypeScript","funding_links":[],"categories":["Table of Contents"],"sub_categories":["Libraries"],"readme":"# Deprecation Warning\n\nKins's Agora powered SDKs have been deprecated and Agora replaced with Kinetic.\n\n## Kinetic\n\nKinetic is an open-source suite of tools that make it easy to build apps that integrate Solana.\n\nIt provides a consistent and clean abstraction over the Solana SDKs and enhances it with some commonly requested features like paying Solana fees on behalf of the user, tracking and timing the users transactions and sending out webhooks.\n\nKinetic is aimed at developers that want to build crypto-experiences for the users of their app, hiding a lot of the details about the blockchain out of sight for both the developer and the end user.\n\nLearn more about Kinetic [here](https://developer.kin.org/docs/kinetic).\n\nSee our new suite of Kinetic SDK's [here](https://developer.kin.org/docs/developers).\n\n# Kin Node SDK\n\nThe Kin Node SDK enables developers use Kin inside their backend servers. It contains support for blockchain actions\nsuch as creating accounts and sending payments, as well a webhook handler class to assist with implementing Agora webhooks. It is recommended that developers read the [website documentation](https://docs.kin.org) prior to using this SDK.\n\n## Requirements\n* Node supporting ES2015 or higher\n\n## Installation\n```\nnpm install @kinecosystem/kin-sdk-v2\n```\n\n```\nyarn add @kinecosystem/kin-sdk-v2\n```\n\nNote: `stellar-base` uses `tweetnacl` and `sodium-native` as dependencies. If `sodium-native` cannot be built,\nor is absent, `stellar-base` falls back to the slower `tweetnacl`. There are certain cases where `sodium-native`\nmay have issues. Notably:\n\n1. Browser environments\n2. Serverless functions with tight package sizing. For example, AWS Lambda has a 50 MiB limit, and `sodium-native`\ntakes up a majority of this space. Developers may wish to delete the `sodium_native` directory in `node_modules/`\nto save space.\n\n## Overview\nThe SDK contains two main components: the `Client` and webhook handlers. The `Client` is used for blockchain\nactions, such as creating accounts sending payments, while the web hook handlers are meant for developers who wish to make\nuse of Agora Webhooks. For a high-level overview of using Agora, please refer to the [website documentation](https://docs.kin.org).\n\n## Client\nThe main component of this library is the `Client` class, which facilitates access to the Kin blockchain.\n\n### Initialization\nAt a minimum, the client needs to be instantiated with an `Environment`.\n\n```typescript\nimport {Client, Environment} from \"@kinecosystem/kin-sdk-v2\";\nconst client = new Client(Environment.Test);\n```\n\nApps with [registered](https://docs.kin.org/app-registration) app indexes should initialize the client with their index:\n\n```typescript\nimport {Client, Environment} from \"@kinecosystem/kin-sdk-v2\";\nconst client = new Client(Environment.Test, {\n    appIndex: 1\n});\n```\n\nAdditional options include:\n- `endpoint`: (optional) A specific endpoint to use in the client. This will be inferred by default from the Environment. Cannot be set if `internal` is set.\n- `internal`: (optional) An `agora.client.InternalClient` instance to use in the client. This will created using default values if not included. Cannot be set if `endpoint` is set.\n- `retryConfig`: A custom `agora.client.RetryConfig` to configure how the client retries requests.\n- `defaultCommitment`: (Kin 4 only) The commitment requirement to use by default for Kin 4 Agora requests. See the [website documentation](https://docs.kin.org/solana#commitment) for more information.\n\n### Usage\n#### Create an Account\nThe `createAccount` method creates an account with the provided private key.\n```typescript\nconst privateKey = PrivateKey.random();\nawait client.createAccount(privateKey);\n```\n\nIn addition to the mandatory `key` parameter, `createAccount` has the following optional parameters:\n- `commitment`: Indicates to Solana which bank state to query. See the [website documentation](https://docs.kin.org/solana#commitment) for more details. \n- `subsidizer`: The private key of an account to use as the funder of the transaction instead of the subsidizer configured on Agora.\n\n#### Get a Transaction\nThe `getTransaction` method gets transaction data by transaction id.\n```typescript\n// txId is either a 32-byte Stellar transaction hash or a 64-byte Solana transaction signature\nconst txId = bs58.decode('\u003cbase58-encoded transaction signature\u003e');  // solana transaction signature\nconst transactionData = await client.getTransaction(txId);\n```\n\nIn addition to the mandatory `txId` parameter, `getTransaction` has the following optional parameters:\n- `commitment`: Indicates to Solana which bank state to query. See the [website documentation](https://docs.kin.org/solana#commitment) for more details. \n\n#### Get an Account Balance\nThe `getBalance` method gets the balance of the provided account, in [quarks](https://docs.kin.org/terms-and-concepts#quark)\n```typescript\nconst publicKey = PublicKey.fromString(\"\");\nconst balance = await client.getBalance(publicKey);\n```\n\nIn addition to the mandatory `account` parameter, `getBalance` has the following optional parameters:\n- `commitment`: Indicates to Solana which bank state to query. See the [website documentation](https://docs.kin.org/solana#commitment) for more details. \n- `accountResolution`: Indicates which type of account resolution to use if the account is not found.\n\n#### Submit a Payment\nThe `submitPayment` method submits the provided payment to Agora.\n```typescript\nconst sender: PrivateKey;\nconst dest: PublicKey;\n\nlet txId = await client.submitPayment({\n    sender: sender,\n    destination: dest,\n    type: TransactionType.Earn,\n    quarks: kinToQuarks(\"1\"),\n});\n```\n\nA `Payment` has the following required properties:\n- `sender`: The private key of the account from which the payment will be sent.\n- `destination`: The public key of the account to which the payment will be sent.\n- `type`: The transaction type of the payment.\n- `quarks`: The amount of the payment, in [quarks](https://docs.kin.org/terms-and-concepts#quark).\n\nAdditionally, it has the following optional properties:\n- `subsidizer`: The private key of an account to use as the funder of the transaction instead of the subsidizer configured on Agora.\n- `invoice`: An [Invoice](https://docs.kin.org/how-it-works#invoices) to associate with this payment. Cannot be set if `memo` is set.\n- `memo`: A text memo to include in the transaction. Cannot be set if `invoice` is set.\n- `dedupeId`: A unique identifier used by the service to help prevent the accidental submission of the same intended transaction twice.\n\n`submitPayment` also has the following optional parameters:\n- `commitment`: Indicates to Solana which bank state to query. See the [website documentation](https://docs.kin.org/solana#commitment) for more details.\n- `senderResolution`: Indicates which type of account resolution to use for the payment sender.\n- `destinationResolution`: Indicates which type of account resolution to use for the payment destination.\n- `senderCreate`: If set to `true` and the destination account is not found, the client will create a token account owned by the submitted destination account.\n\n#### Submit an Earn Batch\nThe `submitEarnBatch` method submits a batch of earns to Agora from a single account. It batches the earns into fewer\ntransactions where possible and submits as many transactions as necessary to submit all the earns.\n```typescript\nconst earns: Earn[] = [\n    {\n        destination: PublicKey.fromString(\"xx\"),\n        quarks: kinToQuarks(\"1\"),\n    },\n    {\n        destination: PublicKey.fromString(\"yy\"),\n        quarks: kinToQuarks(\"1\"),\n    }\n];\nconst result = await client.submitEarnBatch({\n    sender: sender,\n    earns: earns,\n})\n```\n\n\nA single `Earn` has the following properties:\n- `destination`: The public key of the account to which the earn will be sent.\n- `quarks`: The amount of the earn, in [quarks](https://docs.kin.org/terms-and-concepts#quark).\n- `invoice`: (optional) An [Invoice](https://docs.kin.org/how-it-works#invoices) to associate with this earn.\n\nAn `EarnBatch` has the following parameters:\n- `sender`:  The private key of the account from which the earns will be sent.\n- `earns`: The list of earns to send.\n- `memo`: (optional) A text memo to include in the transaction. Cannot be used if the earns have invoices associated with them.\n- `subsidizer`: (optional) The private key of an account to use as the funder of the transaction instead of the subsidizer configured on Agora.\n- `dedupeId`: (optinoal) a unique identifier used by the service to help prevent the accidental submission of the same intended transaction twice. \n\n`submitEarnBatch` also has the following optional parameters:\n- `commitment`: Indicates to Solana which bank state to query. See the [website documentation](https://docs.kin.org/solana#commitment) for more details.\n- `senderResolution`: Indicates which type of account resolution to use for the payment sender.\n- `destinationResolution`: Indicates which type of account resolution to use for the payment destination.\n\n### Examples\nA few examples for creating an account and different ways of submitting payments and batched earns can be found in `examples/client`.\n\n## Webhook Handlers\n\nThe SDK offers handler functions to assist  developers with implementing the [Agora webhooks](https://docs.kin.org/how-it-works#webhooks).\n\nOnly apps that have been assigned an [app index](https://docs.kin.org/app-registration) can make use of Agora webhooks.\n\n### Prerequisites\n\nThe handlers assume usage of the `express` framework, as the default `http` library does not offer\nmuch support for body reading, and middleware.\n\n### Usage\n\nThere are currently two handlers:\n\n- [Events](https://docs.kin.org/how-it-works#events) with `EventsHandler`\n- [Sign Transaction](https://docs.kin.org/how-it-works#sign-transaction) with `SignTransactionHandler`\n\nWhen configuring a webhook, a [webhook secret](https://docs.kin.org/agora/webhook#authentication) can be specified.\n\n#### Events Webhook\n\nTo consume events from Agora:\n\n```typescript\nimport { express, json } from \"express\";\nimport { Event, EventsHandler } from \"@kinecosystem/kin-sdk-v2/webhook\";\n\n// Note: if no secret is provided to the handler, all requests will be processed.\n//       otherwise, the request signature will be validated to ensure it came from agora.\nconst secret = \"WEBHOOK_SECRET\";\n\nconst app = express();\n\n// json() properly reads the entire response body and transforms it into a\n// object suitable for use by the EventsHandler.\napp.use(\"/events\", json());\napp.use(\"/events\", EventsHandler(events: []Event) =\u003e {\n    // processing logic\n}, secret),\n```\n\n#### Sign Transaction Webhook\nThe sign transaction webhook is used to sign Kin 3 transactions with a whitelisted Kin 3 account to remove fees. On Kin 4, the webhook can be used to simply approve or reject transactions submitted by mobile clients. \n\nTo verify and sign transactions related to your app:\n\n```typescript\nimport { express, json } from \"express\";\nimport {\n    SignTransactionRequest,\n    SignTransactionResponse,\n    SignTransactionHandler,\n} from \"@kinecosystem/kin-sdk-v2/webhook\";\n\n// Note: if no secret is provided to the handler, all requests will be processed.\n//       otherwise, the request signature will be validated to ensure it came from agora.\nconst secret = \"WEBHOOK_SECRET\";\n\nconst app = express();\n\n// json() properly reads the entire response body and transforms it into a\n// object suitable for use by the EventsHandler.\napp.use(\"/sign_transaction\", json());\napp.use(\"/sign_transaction\", SignTransactionHandler(req: SignTransactionRequest, resp: SignTransactionResponse) =\u003e {\n    // decide whether or not to sign() or reject() the request.\n}, secret),\n```\n\n### Example Code\n\nA simple example Express server implementing both the Events and Sign Transaction webhooks can be found in `examples/webhook/webhook.tx`. To run it, first install all required dependencies:\n```\n$ npm i\nor\n$ yarn install\n```\n\n\nNext, run it as follows from the root directory (it will run on port 8080):\n```\nexport WEBHOOK_SECRET=yoursecrethere\nexport WEBHOOK_SEED=SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n\nnpx ts-node examples/webhook/webhook.ts\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkinecosystem%2Fkin-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkinecosystem%2Fkin-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkinecosystem%2Fkin-node/lists"}