Skip to content
<awesome-gh-repos>
vic

keybase/keybase-bot

exploration with the keybase chat API
Source code at GitHub null
keybase/keybase-bot.json
{
  "createdAt": "2016-11-21T18:40:51Z",
  "defaultBranch": "master",
  "description": "exploration with the keybase chat API",
  "fullName": "keybase/keybase-bot",
  "homepage": null,
  "language": "TypeScript",
  "name": "keybase-bot",
  "pushedAt": "2025-01-24T00:26:26Z",
  "stargazersCount": 262,
  "topics": [],
  "updatedAt": "2025-11-14T03:30:57Z",
  "url": "https://github.com/keybase/keybase-bot"
}

keybase-bot

Section titled “keybase-bot”

Keybase bot-scripting for Node.js - now written all in TypeScript! Send encrypted data all over this world.

npm Travis CI

You can use this module to script basic Keybase commands such as sending and reading messages and attachments, and managing teams.

Installation

Section titled “Installation”
  1. Install Node.js 12 or above.
  2. Make sure that you have Keybase installed and running.
  3. Install keybase-bot.
    Terminal window
    npm install keybase-bot
    # or
    yarn add keybase-bot

You’re ready to make your first Keybase bot.

Step 1. Initializing your bot

Section titled “Step 1. Initializing your bot”

If your bot is going to do things in the background for an extended period, we recommend starting it up with a username and paper key:

// A simple nodeJS bot that doesn't care who else is logged in on this machine
const Bot = require('keybase-bot')
async function main() {
  const bot = new Bot()
  await bot.init('usernameX', 'some paper key...')
  /* now you can do things with the bot */
  await bot.deinit() // when done
}
main()

This method means it’s running as itself and won’t care about Keybase generally running on your computer. It doesn’t care if you’re logged into Keybase in the GUI app on the same machine. It also doesn’t care if you upgrade Keybase while it’s running, since it won’t restart its copy of Keybase during an update.

If, however, you’d like the bot just to act as you for a quick and easy operation, you can make your bot talk to the same service that the Keybase app is talking to. It will be logged in as whoever’s logged into the Keybase app:

const Bot = require('keybase-bot')
async function main() {
  const bot = new Bot()
  // Make sure you're logged into the Keybase app first!
  // No credentials neeeded:
  await bot.initFromRunningService()
  /* now you can do things with the bot */
  await bot.deinit() // when done
}
main()

Putting it together…a hello world

Section titled “Putting it together…a hello world”

Let’s make a bot that says hello to the Keybase user kbot.

const Bot = require('keybase-bot')


async function main() {
  const bot = new Bot()
  try {
    const username = 'some_username' // put a real username here
    const paperkey = 'foo bar car zar...' // put a real paperkey here
    await bot.init(username, paperkey, {verbose: false})
    console.log(`Your bot is initialized. It is logged in as ${bot.myInfo().username}`)
    const channel = {name: 'kbot'}
    const message = {
      body: `Hello kbot! This is ${bot.myInfo().username} saying hello from my device ${bot.myInfo().devicename}`,
    }
    await bot.chat.send(channel, message)
    console.log('Message sent!')
  } catch (error) {
    console.error(error)
  } finally {
    await bot.deinit()
  }
}


main()

To run the above bot, you want to save that code into a file and run it with node:

Terminal window
node <my-awesome-file-name>.js

Hard-coding paper key into bot isn’t a great idea

Section titled “Hard-coding paper key into bot isn’t a great idea”

You can read it from a secret config file, or pass it as an environment variable - whatever you think is best. For example, you could change the above initialization code to:

const username = process.env.KB_USERNAME
const paperkey = process.env.KB_PAPERKEY
await bot.init(username, paperkey)

And run your program like so:

KB_USERNAME=foo KB_PAPERKEY="foo bar car" node my-awesome-program.js

How to write a bot that listens and replies to messages

Section titled “How to write a bot that listens and replies to messages”

If you’d like to write a bot that listens to your messages (or your team’s) and does something, check out [demos/es7/advertised-echo.js]!(demos/es7/advertised-echo.js).

That demo bot announces itself as handling !echo, which means it gives autocomplete suggestions in the GUI when you talk to it.

Docker usage

Section titled “Docker usage”
  1. Create a bot package, for example save the following code as index.js:
#!/usr/bin/env node
const Bot = require('keybase-bot')


async function main() {
  const bot = new Bot()
  try {
    const username = process.env.KB_USERNAME
    const paperkey = process.env.KB_PAPERKEY
    const target = process.env.KB_TARGET
    await bot.init(username, paperkey, {verbose: false})
    console.log(`Your bot is initialized. It is logged in as ${bot.myInfo().username}`)
    const channel = {name: target + ',' + bot.myInfo().username, public: false, topicType: 'chat'}
    const message = {
      body: `Hello ${target}! This is ${bot.myInfo().username} saying hello from my device ${bot.myInfo().devicename}`,
    }
    await bot.chat.send(channel, message)
    console.log('Message sent!')
  } catch (error) {
    console.error(error)
  } finally {
    await bot.deinit()
  }
}
main()
  1. Prepare a package.json:
{
  "name": "keybase-demo",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "keybase-bot": "^3.0.2"
  }
}
  1. Prepare a Dockerfile:
FROM keybaseio/client:nightly-node
RUN mkdir /app && chown keybase:keybase /app
WORKDIR /app
COPY package*.json ./
RUN npm install # or use yarn
COPY . .
CMD node /app/index.js
  1. Run the following command to build the image:
Terminal window
cd $PROJECT_DIR
docker build -t "keybase-docker-test" .
  1. Start a container to test that it works:
Terminal window
docker run \
  --rm \
  -e KB_USERNAME="yourbotname" \
  -e KB_PAPERKEY="your_paper_key" \
  -e KB_TARGET="yourusername" \
  keybase-docker-test

Development

Section titled “Development”

All the source of this library is now written in TypeScript. If you’re working on the library, please use yarn to install the necessary modules, and then run yarn build to build the JavaScript library files. Finally, make a test config file in __tests__/ (look at __tests__/test.config.ts as an example) and run yarn test. If everything passes, you haven’t broken everything horribly.

API

Section titled “API”

Table of Contents

Section titled “Table of Contents”

Bot

Section titled “Bot”

src/index.ts:17-182

A Keybase bot.

init

Section titled “init”

src/index.ts:53-63

Initialize your bot by starting an instance of the Keybase service and logging in using oneshot mode.

Parameters
Section titled “Parameters”
  • username string The username of your bot’s Keybase account.
  • paperkey string The paperkey of your bot’s Keybase account.
  • options InitOptions? The initialization options for your bot.
Examples
Section titled “Examples”
bot.init('username', 'paperkey')

Returns Promise<void>

initFromRunningService

Section titled “initFromRunningService”

src/index.ts:73-82

Initialize your bot by using an existing running service with a logged in user.

Parameters
Section titled “Parameters”
  • homeDir string? The home directory of this currently running service. Leave blank to use the default homeDir for your system.
  • options InitOptions? The initialization options for your bot.
Examples
Section titled “Examples”
bot.initFromRunningService()

Returns Promise<void>

myInfo

Section titled “myInfo”

src/index.ts:99-101

Get info about your bot!

Examples
Section titled “Examples”
const info = bot.myInfo()

Returns (BotInfo | null) – Useful information like the username, device, and home directory of your bot. If your bot isn’t initialized, you’ll get null.

deinit

Section titled “deinit”

src/index.ts:109-124

Deinitializes the bot by logging out, stopping the keybase service, and removing any leftover login files made by the bot. This should be run before your bot ends.

Examples
Section titled “Examples”
bot.deinit()

Returns Promise<void>

adminDebugLogInfo

Section titled “adminDebugLogInfo”

src/index.ts:133-137

If bot is initialized with an optional directory adminDebugDirectory, this will let you write info text into it.

Parameters
Section titled “Parameters”
Examples
Section titled “Examples”
bot.adminDebugLogInfo('My bot is ready to go.')

Returns Promise<void>

adminDebugLogError

Section titled “adminDebugLogError”

src/index.ts:145-149

If bot is initialized with an optional directory adminDebugDirectory, this will let you write error text into it.

Parameters
Section titled “Parameters”
Examples
Section titled “Examples”
bot.adminDebugLogInfo('My bot is ready to go.')

Returns Promise<void>

Bot Types

Section titled “Bot Types”

A collection of types used by the bot.

Chat

Section titled “Chat”

src/chat-client/index.ts:111-637

Extends ClientBase

The chat module of your Keybase bot. For more info about the API this module uses, you may want to check out keybase chat api.

joinChannel

Section titled “joinChannel”

src/chat-client/index.ts:198-210

Joins a team conversation.

Parameters
Section titled “Parameters”
  • channel chat1.ChatChannel The team chat channel to join.
Examples
Section titled “Examples”
bot.chat.listConvsOnName('team_name').then(async teamConversations => {
  for (const conversation of teamConversations) {
    if (conversation.memberStatus !== 'active') {
      await bot.chat.join(conversation.channel)
      console.log('Joined team channel', conversation.channel)
    }
  }
})

Returns Promise<void>

leaveChannel

Section titled “leaveChannel”

src/chat-client/index.ts:225-237

Leaves a team conversation.

Parameters
Section titled “Parameters”
  • channel chat1.ChatChannel The team chat channel to leave.
Examples
Section titled “Examples”
bot.chat.listConvsOnName('team_name').then(async teamConversations => {
  for (const conversation of teamConversations) {
    if (conversation.memberStatus === 'active') {
      await bot.chat.leave(conversation.channel)
      console.log('Left team channel', conversation.channel)
    }
  }
})

Returns Promise<void>

getUnfurlSettings

Section titled “getUnfurlSettings”

src/chat-client/index.ts:386-393

Gets current unfurling settings

Examples
Section titled “Examples”
bot.chat.getUnfurlSettings().then(mode => console.log(mode))

Returns Promise<chat1.UnfurlSettings>

setUnfurlSettings

Section titled “setUnfurlSettings”

src/chat-client/index.ts:407-413

Sets the unfurling mode In Keybase, unfurling means generating previews for links that you’re sending in chat messages. If the mode is set to always or the domain in the URL is present on the whitelist, the Keybase service will automatically send a preview to the message recipient in a background chat channel.

Parameters
Section titled “Parameters”
  • mode chat1.UnfurlSettings the new unfurl mode
Examples
Section titled “Examples”
bot.chat
  .setUnfurlMode({
    mode: 'always',
  })
  .then(mode => console.log('mode updated!'))

Returns Promise<void>

loadFlip

Section titled “loadFlip”

src/chat-client/index.ts:424-441

Loads a flip’s details

Parameters
Section titled “Parameters”
  • conversationID string conversation ID received in API listen.
  • flipConversationID string flipConvID from the message summary.
  • messageID number ID of the message in the conversation.
  • gameID string gameID from the flip message contents.
Examples
Section titled “Examples”
// check demos/es7/poker-hands.js

Returns Promise<chat1.UICoinFlipStatus>

advertiseCommands

Section titled “advertiseCommands”

src/chat-client/index.ts:462-468

Publishes a commands advertisement which is shown in the ”!” chat autocomplete.

Parameters
Section titled “Parameters”
  • advertisement Advertisement details of the advertisement
Examples
Section titled “Examples”
await bot.chat.advertiseCommands({
  advertisements: [
    {
      type: 'public',
      commands: [
        {
          name: '!echo',
          description: 'Sends out your message to the current channel.',
          usage: '[your text]',
        },
      ],
    },
  ],
})

Returns Promise<void>

clearCommands

Section titled “clearCommands”

src/chat-client/index.ts:476-482

Clears all published commands advertisements.

Parameters
Section titled “Parameters”
  • advertisement advertisement parameters
Examples
Section titled “Examples”
await bot.chat.clearCommands()

Returns Promise<void>

listCommands

Section titled “listCommands”

src/chat-client/index.ts:504-511

Lists all commands advertised in a channel.

Parameters
Section titled “Parameters”
  • lookup AdvertisementsLookup either conversation id or channel
Examples
Section titled “Examples”
const commandsList = await bot.chat.listCommands({
  channel: channel,
})
console.log(commandsList)
// prints out something like:
// {
//   commands: [
//     {
//       name: '!helloworld',
//       description: 'sample description',
//       usage: '[command arguments]',
//       username: 'userwhopublished',
//     }
//   ]
// }

Returns Promise<{commands: Array<chat1.UserBotCommandOutput>}>

list

Section titled “list”

src/chat-client/index.ts:121-128

Lists your chats, with info on which ones have unread messages.

Parameters
Section titled “Parameters”
  • options ChatListOptions? An object of options that can be passed to the method.
Examples
Section titled “Examples”
const chatConversations = await bot.chat.list({unreadOnly: true})
console.log(chatConversations)

Returns Promise<Array<chat1.ConvSummary>> An array of chat conversations. If there are no conversations, the array is empty.

listChannels

Section titled “listChannels”

src/chat-client/index.ts:139-155

Lists conversation channels in a team

Parameters
Section titled “Parameters”
Examples
Section titled “Examples”
bot.chat.listChannels('team_name').then(chatConversations => console.log(chatConversations))

Returns Promise<Array<chat1.ConvSummary>> An array of chat conversations. If there are no conversations, the array is empty.

read

Section titled “read”

src/chat-client/index.ts:166-183

Reads the messages in a conversation. You can read with or without marking as read.

Parameters
Section titled “Parameters”
  • channelOrConversationId chat1.ChatChannel or chat1.ConvIDStr The chat conversation to send the message in.
  • options ChatReadOptions? An object of options that can be passed to the method.
Examples
Section titled “Examples”
alice.chat.read(channel).then(messages => console.log(messages))

Returns Promise<ReadResult> A summary of data about a message, including who send it, when, the content of the message, etc. If there are no messages in your channel, then an error is thrown.

send

Section titled “send”

src/chat-client/index.ts:250-268

Send a message to a certain conversation.

Parameters
Section titled “Parameters”
  • channelOrConversationId chat1.ChatChannel or chat1.ConvIDStr The chat conversation to send the message in.
  • message chat1.ChatMessage The chat message to send.
  • options ChatSendOptions? An object of options that can be passed to the method.
Examples
Section titled “Examples”
const channel = {name: 'kbot,' + bot.myInfo().username, public: false, topicType: 'chat'}
const message = {body: 'Hello kbot!'}
bot.chat.send(channel, message).then(() => console.log('message sent!'))
const onMessage = async message => {
  bot.chat.send(message.conversationId, {
    body: 'hello!',
  })
}
await bot.chat.watchAllChannelsForNewMessages(onMessage, onError)

Returns Promise<chat1.SendRes>

createChannel

Section titled “createChannel”

src/chat-client/index.ts:277-290

Creates a new blank conversation.

Parameters
Section titled “Parameters”
  • channel chat1.ChatChannel The chat channel to create.
Examples
Section titled “Examples”
bot.chat.createChannel(channel).then(() => console.log('conversation created'))

Returns Promise<void>

attach

Section titled “attach”

src/chat-client/index.ts:301-309

Send a file to a conversation.

Parameters
Section titled “Parameters”
  • channelOrConversationId chat1.ChatChannel or chat1.ConvIDStr The chat conversation to send the message in.
  • filename string The absolute path of the file to send.
  • options ChatAttachOptions? An object of options that can be passed to the method.
Examples
Section titled “Examples”
bot.chat.attach(channel, '/Users/nathan/my_picture.png').then(() => console.log('Sent a picture!'))

Returns Promise<chat1.SendRes>

download

Section titled “download”

src/chat-client/index.ts:321-328

Download a file send via Keybase chat.

Parameters
Section titled “Parameters”
  • channelOrConversationId chat1.ChatChannel or chat1.ConvIDStr The chat conversation to send the message in.
  • messageId number The message id of the attached file.
  • output string The absolute path of where the file should be downloaded to.
  • options ChatDownloadOptions? An object of options that can be passed to the method
Examples
Section titled “Examples”
bot.chat.download(channel, 325, '/Users/nathan/Downloads/file.png')

Returns Promise<void>

react

Section titled “react”

src/chat-client/index.ts:341-355

Reacts to a given message in a conversation. Messages have messageId’s associated with them, which you can learn in bot.chat.read.

Parameters
Section titled “Parameters”
  • channelOrConversationId chat1.ChatChannel or chat1.ConvIDStr The chat conversation to send the message in.
  • messageId number The id of the message to react to.
  • reaction string The reaction emoji, in colon form.
  • options ChatReactOptions? An object of options that can be passed to the method.
Examples
Section titled “Examples”
bot.chat.react(channel, 314, ':+1:').then(() => console.log('Thumbs up!'))

Returns Promise<chat1.SendRes>

delete

Section titled “delete”

src/chat-client/index.ts:368-379

Deletes a message in a conversation. Messages have messageId’s associated with them, which you can learn in bot.chat.read. Known bug: the GUI has a cache, and deleting from the CLI may not become apparent immediately.

Parameters
Section titled “Parameters”
  • channelOrConversationId chat1.ChatChannel or chat1.ConvIDStr The chat conversation to send the message in.
  • messageId number The id of the message to delete.
  • options ChatDeleteOptions? An object of options that can be passed to the method.
Examples
Section titled “Examples”
bot.chat.delete(channel, 314).then(() => console.log('message deleted!'))

Returns Promise<void>

watchChannelForNewMessages

Section titled “watchChannelForNewMessages”

src/chat-client/index.ts:530-538

Listens for new chat messages on a specified channel. The onMessage function is called for every message your bot receives. This is pretty similar to watchAllChannelsForNewMessages, except it specifically checks one channel. Note that it receives messages your own bot posts, but from other devices. You can filter out your own messages by looking at a message’s sender object. Hides exploding messages by default.

Parameters
Section titled “Parameters”
  • channel chat1.ChatChannel The chat channel to watch.
  • onMessage OnMessage A callback that is triggered on every message your bot receives.
  • onError OnError? A callback that is triggered on any error that occurs while the method is executing.
  • options ListenOptions? Options for the listen method.
Examples
Section titled “Examples”
// Reply to all messages between you and `kbot` with 'thanks!'
const channel = {name: 'kbot,' + bot.myInfo().username, public: false, topicType: 'chat'}
const onMessage = message => {
  const conversationId = message.conversationId
  bot.chat.send(conversationId, {body: 'thanks!!!'})
}
bot.chat.watchChannelForNewMessages(channel, onMessage)

Returns Promise<void>

watchAllChannelsForNewMessages

Section titled “watchAllChannelsForNewMessages”

src/chat-client/index.ts:561-564

This function will put your bot into full-read mode, where it reads everything it can and every new message it finds it will pass to you, so you can do what you want with it. For example, if you want to write a Keybase bot that talks shit at anyone who dares approach it, this is the function to use. Note that it receives messages your own bot posts, but from other devices. You can filter out your own messages by looking at a message’s sender object. Hides exploding messages by default.

Note that if your bot was added into a channel as a restricted bot, it won’t have access to channel names. So you should be using conversationId when responding in the same conversation.

Parameters
Section titled “Parameters”
  • onMessage OnMessage A callback that is triggered on every message your bot receives.
  • onError OnError? A callback that is triggered on any error that occurs while the method is executing.
  • options ListenOptions? Options for the listen method.
Examples
Section titled “Examples”
// Reply to incoming traffic on all channels with 'thanks!'
const onMessage = message => {
  const conversationId = message.conversationId
  bot.chat.send(conversationId, {body: 'thanks!!!'})
}
bot.chat.watchAllChannelsForNewMessages(onMessage)

Returns Promise<void>

Chat Types

Section titled “Chat Types”

A collection of types used by the Chat module.

ChatAttachOptions

Section titled “ChatAttachOptions”

src/chat-client/index.ts:54-58

Options for the attach method of the chat module.

ChatDownloadOptions

Section titled “ChatDownloadOptions”

src/chat-client/index.ts:63-67

Options for the download method of the chat module.

ChatReactOptions

Section titled “ChatReactOptions”

src/chat-client/index.ts:72-74

Options for the react method of the chat module.

ChatDeleteOptions

Section titled “ChatDeleteOptions”

src/chat-client/index.ts:79-81

Options for the delete method of the chat module.

OnMessage

Section titled “OnMessage”

src/chat-client/index.ts:8-8

A function to call when a message is received.

Type: function (message: chat1.MsgSummary): (void | Promise<void>)

OnError

Section titled “OnError”

src/chat-client/index.ts:10-10

A function to call when an error occurs.

Type: function (error: Error): (void | Promise<void>)

ListenOptions

Section titled “ListenOptions”

src/chat-client/index.ts:90-93

Options for the methods in the chat module that listen for new messages. Local messages are ones sent by your device. Including them in the output is useful for applications such as logging conversations, monitoring own flips and building tools that seamlessly integrate with a running client used by the user.

Team

Section titled “Team”

src/team-client/index.ts:20-69

Extends ClientBase

The team module of your Keybase bot. For more info about the API this module uses, you may want to check out keybase team api.

addMembers

Section titled “addMembers”

src/team-client/index.ts:29-37

Add a bunch of people with different privileges to a team

Parameters
Section titled “Parameters”
  • additions AddMembersParam an array of the users to add, with privs
Examples
Section titled “Examples”
bot.team
  .addMembers({
    team: 'phoenix',
    emails: [
      {email: 'alice@keybase.io', role: 'writer'},
      {email: 'cleo@keybase.io', role: 'admin'},
    ],
    usernames: [
      {username: 'frank', role: 'reader'},
      {username: 'keybaseio@twitter', role: 'writer'},
    ],
  })
  .then(res => console.log(res))

Returns Promise<keybase1.TeamAddMemberResult> A result object of adding these members to the team.

removeMember

Section titled “removeMember”

src/team-client/index.ts:46-50

Remove someone from a team.

Parameters
Section titled “Parameters”
  • removal RemoveMemberParam object with the team name and username
Examples
Section titled “Examples”
bot.team.removeMember({team: 'phoenix', username: 'frank'}).then(res => console.log(res))

Returns Promise<void>

listTeamMemberships

Section titled “listTeamMemberships”

src/team-client/index.ts:60-68

List a team’s members.

Parameters
Section titled “Parameters”
  • team ListTeamMembershipsParam an object with the team name in it.
Examples
Section titled “Examples”
bot.team.listTeamMemberships({team: 'phoenix'}).then(res => console.log(res))

Returns Promise<keybase1.TeamDetails> Details about the team.

Team Types

Section titled “Team Types”

A collection of types used by the Team module.

Wallet

Section titled “Wallet”

src/wallet-client/index.ts:5-149

Extends ClientBase

The wallet module of your Keybase bot. For more info about the API this module uses, you may want to check out keybase wallet api.

balances

Section titled “balances”

src/wallet-client/index.ts:13-20

Provides a list of all accounts owned by the current Keybase user.

Examples
Section titled “Examples”
bot.wallet.balances().then(accounts => console.log(accounts))

Returns Promise<Array<stellar1.OwnAccountCLILocal>> An array of accounts. If there are no accounts, the array is empty.

history

Section titled “history”

src/wallet-client/index.ts:30-42

Provides a list of all transactions in a single account.

Parameters
Section titled “Parameters”
  • accountId stellar1.AccountID The id of an account owned by a Keybase user.
Examples
Section titled “Examples”
bot.wallet.history('GDUKZH6Q3U5WQD4PDGZXYLJE3P76BDRDWPSALN4OUFEESI2QL5UZHCK').then(transactions => console.log(transactions))

Returns Promise<Array<stellar1.PaymentCLILocal>> An array of transactions related to the account.

details

Section titled “details”

src/wallet-client/index.ts:52-60

Get details about a particular transaction

Parameters
Section titled “Parameters”
  • transactionId stellar1.TransactionID The id of the transaction you would like details about.
Examples
Section titled “Examples”
bot.wallet.details('e5334601b9dc2a24e031ffeec2fce37bb6a8b4b51fc711d16dec04d3e64976c4').then(details => console.log(details))

Returns Promise<stellar1.PaymentCLILocal> An object of details about the transaction specified.

lookup

Section titled “lookup”

src/wallet-client/index.ts:74-87

Lookup the primary Stellar account ID of a Keybase user.

Parameters
Section titled “Parameters”
  • name string The name of the user you want to lookup. This can be either a Keybase username or a username of another account that is supported by Keybase if it is followed by an ’@’.
Examples
Section titled “Examples”
const lookup1 = bot.wallet.lookup('patrick')
// 'patrick' on Keybase is 'patrickxb' on twitter
const lookup2 = bot.wallet.lookup('patrcikxb@twitter')
// Using Lodash's `isEqual` since objects with same values aren't equal in JavaScript
_.isEqual(lookup1, lookup2) // => true

Returns Promise<{accountId: stellar1.AccountID, username: string}> An object containing the account ID and Keybase username of the found user.

send

Section titled “send”

src/wallet-client/index.ts:103-111

Send lumens (XLM) via Keybase with your bot!

Parameters
Section titled “Parameters”
  • recipient string Who you’re sending your money to. This can be a Keybase user, stellar address, or a username of another account that is supported by Keybase if it is followed by an ’@’.
  • amount string The amount of XLM to send.
  • currency string? Adds a currency value to the amount specified. For example, adding ‘USD’ would send
  • message string? The message for your payment
Examples
Section titled “Examples”
bot.wallet.send('nathunsmitty', '3.50') // Send 3.50 XLM to Keybase user `nathunsmitty`
bot.wallet.send('nathunsmitty@github', '3.50') // Send 3.50 XLM to GitHub user `nathunsmitty`
bot.wallet.send('nathunsmitty', '3.50', 'USD') // Send $3.50 worth of lumens to Keybase user `nathunsmitty`
bot.wallet.send('nathunsmitty', '3.50', 'USD', 'Shut up and take my money!') // Send $3.50 worth of lumens to Keybase user `nathunsmitty` with a memo

Returns Promise<stellar1.PaymentCLILocal> The trasaction object of the transaction.

batch

Section titled “batch”

src/wallet-client/index.ts:124-132

Send lumens (XLM) via Keybase to more than one user at once. As opposed to the normal bot.wallet.send command, this can get multiple transactions into the same 5-second Stellar ledger.

Parameters
Section titled “Parameters”
  • batchId string example, if sending a bunch of batches for an airdrop, you could pass them all airdrop2025.
  • payments Array<stellar1.BatchPaymentArg> an array of objects containing recipients and XLM of the form {“recipient”: “someusername”, “amount”: “1.234”, “message”, “hi there”}
Examples
Section titled “Examples”
bot.wallet.batch('airdrop2040', [
  {recipient: 'a1', amount: '1.414', message: 'hi a1, yes 1'},
  {recipient: 'a2', amount: '3.14159', message: 'hi a2, yes 2'},
])

Returns Promise<stellar1.BatchResultLocal> an object

cancel

Section titled “cancel”

src/wallet-client/index.ts:141-148

If you send XLM to a Keybase user who has not established a wallet, you can cancel the payment before the recipient claims it and the XLM will be returned to your account.

Parameters
Section titled “Parameters”
  • transactionId stellar1.TransactionID The id of the transaction to cancel.
Examples
Section titled “Examples”
bot.wallet
  .cancel('e5334601b9dc2a24e031ffeec2fce37bb6a8b4b51fc711d16dec04d3e64976c4')
  .then(() => console.log('Transaction successfully canceled!'))

Returns Promise<void>

Wallet Types

Section titled “Wallet Types”

A collection of types used by the Wallet module.

ChatListOptions

Section titled “ChatListOptions”

src/chat-client/index.ts:15-20

Options for the list method of the chat module.

ChatListChannelsOptions

Section titled “ChatListChannelsOptions”

src/chat-client/index.ts:25-28

Options for the listChannels method of the chat module.

ChatReadOptions

Section titled “ChatReadOptions”

src/chat-client/index.ts:33-39

Options for the read method of the chat module.

ChatSendOptions

Section titled “ChatSendOptions”

src/chat-client/index.ts:44-49

Options for the send method of the chat module.

Contributions

Section titled “Contributions”

Make sure that you have Node, Yarn, and the Keybase application installed. We also use developer tools such as EditorConfig, ESLint, Flow, and Prettier so you’ll probably want to make sure that your development is configured to use those tools somewhere in your code writing process.

Setting up the source code

Section titled “Setting up the source code”
  1. Clone this repo.
  2. Install dependencies with yarn.
  3. Make your changes in src/.
  4. Build the bot in watch mode with yarn dev.
  5. Build the bot for production with yarn build to update lib/.
  6. Build the docs for the bot with yarn docs.

That’s it. We accept changes via Pull Requests; please make sure that any changes you make build successfully and pass Flow, Prettier, and ESLint checks. We’d also really appreciate it if your PR could follow the Conventional Commit specification. If you’re adding a new feature, please add/update tests, demos, documentation, and whatever else makes sense to go with it. If you have any questions about contributing, please feel free to ask a maintainer!

Running Tests

Section titled “Running Tests”

We run tests using Jest. All tests are run against actual Keybase processes that are created and destroyed during testing and ping the actual Keybase server to do things like send messages and XLM. To facilitate this, the tests read a file in __tests__/test.config.ts that contains usernames, paperkeys, and team names that are used during testing. You’ll need three test Keybase accounts, two teams, and some Stellar Lumens to run all tests.

  1. Copy __tests__/test.config.example.ts as __tests__/test.config.ts. Note that __tests__/test.config.ts should NOT be version controlled, as it will contain paper keys!
  2. Edit __tests__/test.config.ts as it specifies, replacing the placeholder values with actual usernames, paperkeys, and team names.
  3. Run yarn test. Everything should pass!

Generating Types

Section titled “Generating Types”

Most of the types the bot uses are generated from definitions defined in the protocol/ directory inside the Keybase client repo. This ensures that the types that the bot uses are consistent across bots and always up to date with the output of the API.

To build the types for the TypeScript bot, you’ll need to clone the client repo. This requires Go and your GOPATH to be set up.

Terminal window
go get github.com/keybase/client/go/keybase

and install the necessary dependencies for compiling the protocol files. This requires node.js and Yarn.

Terminal window
cd client/protocol
yarn install

Then you can generate the types by using the provided Makefile in this repo.

Terminal window
cd path/to/keybase-bot
make

Should you need to remove all the types for some reason, you can run make clean.

Release

Section titled “Release”

We automatically generate a CHANGELOG and version (using Semantic Versioning) keybase-bot with standard-version. To cut a new release:

  1. Make sure all commits that are to be included in the release are squash-merged into master branch.
  2. On your local copy of the bot, checkout master and ensure it’s up to date with origin/master.
  3. Run standard-version with the command yarn release.
  4. Push the new git tags to origin. (git push --follow-tags origin master)
  5. Publish to npm with yarn publish.

License

Section titled “License”

BSD-3-Clause

Post issues to: https://github.com/keybase/keybase-issues