https://github.com/merklejerk/send-tokens
Simple CLI tool to send ERC20 tokens with a private key, mnemonic, or keystore.
https://github.com/merklejerk/send-tokens
airdrop cli ens erc20 es2017 ethereum private-key self-signed send tokens transfer wallet
Last synced: 6 months ago
JSON representation
Simple CLI tool to send ERC20 tokens with a private key, mnemonic, or keystore.
- Host: GitHub
- URL: https://github.com/merklejerk/send-tokens
- Owner: merklejerk
- License: apache-2.0
- Created: 2018-07-24T22:36:12.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2023-01-23T20:53:33.000Z (over 2 years ago)
- Last Synced: 2025-03-15T17:38:57.826Z (7 months ago)
- Topics: airdrop, cli, ens, erc20, es2017, ethereum, private-key, self-signed, send, tokens, transfer, wallet
- Language: JavaScript
- Size: 525 KB
- Stars: 30
- Watchers: 2
- Forks: 10
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.org/merklejerk/send-tokens)
[](https://www.npmjs.com/package/send-tokens)
# send-tokens
A simple CLI tool (and library) for sending Ethereum ERC20 tokens using any of the following:
- A wallet's private key
- A keystore file
- An HD wallet mnemonic phrase
- A provider (node) wallet address
For the ether version of this package, check out
[send-ether](https://github.com/merklejerk/send-ether).
### Migrating from 1.x:
Token amounts are now in **whole** units, by default, which is defined by the number
of decimal places a token contract supports. This means sending `100.123` tokens
with a token that supports 18 decimal places, will actually send
`100.123 * 10^18` of the smallest unit of that token. This behavior can be
overridden with the `--decimals` option.
### Contents
- [Installation](#installation)
- [Examples](#examples)
- [All Options](#all-options)
- [JSON Logs](#json-logs)
- [ENS Names](#ens-names)
- [Library Usage](#library-usage)
## Installation
```bash
npm install -g send-tokens
# or
yarn global add send-tokens
```
## Examples
```bash
# Address of token contract. May also be an ENS name.
TOKEN='0x1658164265555FA310d20bC601Dd32e9b996A436'
# Recipient of tokens. May also be an ENS name.
DST='0x0420DC92A955e3e139b52142f32Bd54C6D46c023'
# Sending wallet's private key.
PRIVATE_KEY='0x52c251b9e04740157471a724e9a3210b83fac5834b29c89d5bd57661bd2a7057'
# Sending wallet's HD mnemonic.
MNEMONIC='butter crepes sugar flour eggs milk ...'
# Send 100.53 WHOLE tokens to an address,
# on the mainnet, using a wallet's private key
$ send-tokens --key $PRIVATE_KEY $TOKEN $DST 100.53
# Send 32 of the smallest units of a token to an address, on ropsten,
# using an HD wallet mnemonic
$ send-tokens --network ropsten --mnemonic "$MNEMONIC" $TOKEN $DST 32 -d 0
# Send 99 WHOLE tokens to an address, on the mainnet,
# using a keystore file.
$ send-tokens --keystore './path/to/keystore.json' --password 'secret' $TOKEN $DST 99
# Send 64.3163512 WHOLE tokens to an address, on the provider's network,
# using the provider's default wallet, and wait for 3 confirmations.
$ send-tokens --provider 'http://localhost:8545' --confirmations 3 $TOKEN $DST 64.3163512
```
## All Options
```
$ send-tokens --help
Usage: send-tokens [options]
Options:
-v, --version output the version number
-d, --decimals decimal places amount is expressed in (default: max token supports)
-k, --key sending wallet's private key
-f, --key-file sending wallet's private key file
-s, --keystore-file sending wallet's keystore file
--password sending wallet's HD wallet phrase
--mnemonic-index sending wallet's HD wallet account index (default: 0)
-a, --account sending wallet's account address (provider wallet)
-c, --confirmations number of confirmations to wait for before returning (default: 0)
-p, --provider provider URI
-n, --network network name
-G, --gas-price explicit gas price, in gwei (e.g., 20)
-l, --log append a JSON log to a file
--no-confirm bypass confirmation
-h, --help output usage information
```
## JSON Logs
If you pass the `--log` option, a JSON object describing the transfer
will be appended to a file when the transaction is mined, one object per line.
##### Log Entries
Log entries follow this structure:
```js
{
// Unique transfer ID to identify related logs.
id: '88fdd8a4b8084c36',
// UNIX time.
time: 1532471209842,
// Address of token contract.
token: '0x1658164265555FA310d20bC601Dd32e9b996A436',
// Address of sender.
from: '0x0420DC92A955e3e139b52142f32Bd54C6D46c023',
// Address of recipient.
to: '0x2621Ea417659Ad69BAE66AF05eBE5788e533E5e8',
// Amount of tokens sent (in weis).
amount: '20',
// Transaction ID of transfer.
txId: '0xd9255f8365305ebffd77cb30d09f82745eaa232e42739f5fc2788fa46f1347e3',
// Block number where the transfer was mined.
block: 4912040,
// Gas used.
gas: 40120
}
```
## ENS Names
Anywhere you can pass an address, you can also pass an ENS name, like
`'ethereum.eth'`, and the it will automatically be resolved to a real
address.
ENS resolution only works on the mainnet, rinkeby, and ropsten, and the name
must be fully registered with the ENS contract and a resolver.
## Library Usage
The `send-tokens` package can be used as a library through the `sendTokens()`
function.
`sendTokens()` asynchronously resolves to a
[transaction receipt](https://web3js.readthedocs.io/en/1.0/web3-eth.html#eth-gettransactionreceipt-return)
once the transaction has been mined (or confirmed, if the
`confirmations` option is > 0).
#### sendTokens() Examples
```js
const {sendTokens} = require('send-tokens');
// Address of token contract.
const TOKEN_ADDRESS = '0x1658164265555FA310d20bC601Dd32e9b996A436';
// Recipient of tokens.
const RECIPIENT = '0x0420DC92A955e3e139b52142f32Bd54C6D46c023';
// Sending wallet's private key.
const PRIVATE_KEY = '0x52c251b9e04740157471a724e9a3210b83fac5834b29c89d5bd57661bd2a7057';
// Send 100 WHOLE tokens of tokens to someone using a private key and wait for
// it to be mined.
let receipt = await sendTokens(TOKEN_ADDRESS, RECIPIENT, '100',
{key: PRIVATE_KEY});
// Sending wallet's mnemonic.
const MNEMONIC = 'butter crepes sugar flour eggs milk ...';
// Send 100.312 WHOLE tokens to someone using a (BIP39) mnemonic phrase
// and wait for it to be mined and confirmed 3 times.
receipt = await sendTokens(TOKEN_ADDRESS, RECIPIENT, '100.312',
{mnemonic: MNEMONIC, confirmations: 3});
// Sending wallet's keystore file contents as a string.
const KEYSTORE = '{...}';
// Keystore password.
const PASSWORD = 'secret';
// Send 32 of the smallest unit of tokens to someone using a keystore file,
// print the transaction ID when it's available, and wait for it to be mined.
receipt = await sendTokens(TOKEN_ADDRESS, RECIPIENT, '32', {
keystore: KEYSTORE,
password: PASSWORD,
decimals: 0,
onTxId: console.log
});
```
#### Full sendTokens() Options
```js
const {sendTokens} = require('send-tokens');
// Send TOKEN_AMOUNT tokens to RECIPIENT via the token contract at
// TOKEN_ADDRESS.
{tx: Object} = async sendTokens(
// Address of token contract.
// Should be a hex string ('0x...')
TOKEN_ADDRESS: String,
// Address of recipient.
// Should be a hex string ('0x...')
RECIPIENT: String,
// Amount of tokens to send. Units depend on `decimals` option.
// Should be a base-10 decimal string (e.g., '1234.56').
TOKEN_AMOUNT: String,
// Options object
{
// Suppress output.
quiet: Boolean,
// If specified, append to a JSON log file at this path.
log: String,
// Call this function, passing the transaction hash/ID of the transaction
// once it becomes available (transaction is posted to the blockchain but
// not yet mined).
onTxId: Function,
// Decimal places of token amount.
// E.g., 18 for 18 decimal places, 0 for smallest units.
// Defaults to maximum decimal places supported by token contract.
decimals: Number,
// If connecting to a custom provider (e.g., a private node), this
// can be the set to the address of an unlocked wallet on the provider
// from which to send the tokens.
account: String,
// Hex-encoded 32-byte private key of sender (e.g., '0x1234...').
key: String,
// BIP39 mnemonic phrase of sender.
mnemonic: String,
// Sender's Mnemonic account index. Defaults to 0.
mnemonicIndex: Number,
// Sender's JSON-encoded keystore file contents.
keystore: String,
// Sender's keystore file path.
keystoreFile: String,
// Keystore password.
password: String,
// Ethereum network to use. May be 'main', 'ropsten', 'rinkeby', or 'kovan'.
// Defaults to 'main',
network: String,
// Gas price for the transaction.
// Should be a number in gweis.
// Defaults to current network gas price.
gasPrice: Number,
// Number of confirmations to wait for after the transaction is mined.
// Maximum of 12. Defaults to 0 (no confirmations).
confirmations: Number,
// Infura API key to use.
infuraKey: String,
// Custom provider. May either be a URI (e.g., http://localhost:8545) or
// a Provider object from Web3.
provider: String | Object,
// Custom web3 object.
web3: Object
});
```
#### toWallet()
Another exposed library function is `toWallet()`, which returns an address
& private key pair from a private key, mnemonic, or keystore. Below are the
full options.
```js
const {toWallet} = require('send-tokens');
// Convert a private key, mnemonic, or keystore to an address and private-key
// pair object. Both fields will be a hex-encoded string.
{address: String, key: String} = toWallet({
// Hex-encoded 32-byte private key of sender (e.g., '0x1234...').
key: String,
// BIP39 mnemonic phrase.
mnemonic: String,
// Mnemonic account index. Defaults to 0.
mnemonicIndex: Number,
// JSON-encoded keystore file contents.
keystore: String,
// Keystore password (if `keystore` is passed).
password: String
});
```