Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to BTCPay Server

Scalekit connector
Open markdown

The BTCPay Server connector lets your AI agent act in each user's BTCPay Server account. Each user connects their own BTCPay Server API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 60 tools.

Tools
60
What they doRead · write · destructive
33 · 21 · 633 read21 write6 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>
  3. Create the BTCPay Server connection

    In AgentKit > Connections, create a BTCPay Server connection. The name you give it is the connection_name your code passes. See Configure connections.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    const scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENVIRONMENT_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    const connector = 'btcpay'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize BTCPay Server:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'btcpay_current_user_get',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their BTCPay Server credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • btcpay_app_sales_getGet sales statistics for a Point of Sale or Crowdfund app over recent days.Read-only

    Get App Sales

    Get sales statistics for a Point of Sale or Crowdfund app over recent days. Returns the total sales count and a per-day series. Use it to report app activity.

    Inputs

    app_idstringrequired
    App ID. Example: 3Ki9vC6eF2ZsEXbXV2tQWQ8d1Sp.
    number_of_daysnumber
    How many of the last days. Defaults to 7. Example: 7.
  • btcpay_apps_listList the apps of a store (Point of Sale, Crowdfund and others).Read-only

    List Store Apps

    List the apps of a store (Point of Sale, Crowdfund and others). Returns each app's id, name, type and creation time. Use app_sales_get for an app's sales.

    Inputs

    store_idstringrequired
    The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
  • btcpay_current_user_getGet the BTCPay user that owns the API key.Read-only

    Get Current User

    Get the BTCPay user that owns the API key. Returns the user's id, email, name, roles and creation date. Use it to confirm which account the connection acts as.

    Inputs

    This tool takes no inputs.

  • btcpay_invoice_getGet one invoice by ID.Read-only

    Get Invoice

    Get one invoice by ID. Returns its status, additionalStatus, amount, currency, checkoutLink, metadata, checkout settings and timestamps. Use invoice_payment_methods_get to see addresses, rates and received payments.

    Inputs

    invoice_idstringrequired
    The invoice ID. Example: HMprBnL9BTXWuPvpoKBS6e.
    store_idstringrequired
    ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
    include_payment_methodsboolean
    Includes payment methods available to the response. Defaults to false. Example: false.
  • btcpay_invoice_payment_methods_getGet the payment methods of an invoice.Read-only

    Get Invoice Payment Methods

    Get the payment methods of an invoice. Returns, per method, the destination address or BOLT11, payment link, rate, amount due, amount paid and the list of received payments. Use it to check how and how much an invoice has been paid.

    Inputs

    invoice_idstringrequired
    The invoice ID. Example: HMprBnL9BTXWuPvpoKBS6e.
    store_idstringrequired
    ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
    include_sensitiveboolean
    If true, additionalData might include sensitive data (such as xpub). Requires the permission btcpay.store.canmodifystoresettings. Defaults to false. Example: false.
    only_accounted_paymentsboolean
    If default or true, only returns payments which are accounted (in Bitcoin, this mean not returning RBF'd or double spent payments). Example: true.
  • btcpay_invoices_listList a store's invoices, newest first, with optional filters by order ID, status, text and date range.Read-only

    List Invoices

    List a store's invoices, newest first, with optional filters by order ID, status, text and date range. Returns each invoice's id, status, amount, currency, checkout link, metadata and timestamps. Use invoice_get for one invoice and invoice_payment_methods_get for its payments.

    Inputs

    store_idstringrequired
    The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
    end_dateinteger
    End date of the period to retrieve invoices. Example: 1592312018.
    include_payment_methodsboolean
    Includes payment methods available to the response. Defaults to false. Example: false.
    order_idarray
    Array of OrderIds to fetch the invoices for. Example: ["order-1001"]
    skipinteger
    Number of records to skip. Example: 0.
    start_dateinteger
    Start date of the period to retrieve invoices. Example: 1592312018.
    statusstring
    Array of statuses of invoices to be fetched. Example: Settled.one of ExpiredInvalidNewProcessingSettled
    takeinteger
    Number of records returned in response. Example: 10.
    text_searchstring
    A term that can help locating specific invoices. Example: order-1001.
  • btcpay_lightning_balance_getGet the balance of the store's Lightning node.Read-only

    Get Lightning Balance

    Get the balance of the store's Lightning node. Returns on-chain and off-chain (channel) balances in millisatoshi. Use lightning_info_get for node details.

    Inputs

    crypto_codestringrequired
    The cryptoCode of the lightning-node to query. Example: BTC.
    store_idstringrequired
    The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
  • btcpay_lightning_info_getGet information about the Lightning node connected to a store.Read-only

    Get Lightning Node Info

    Get information about the Lightning node connected to a store. Returns the node URIs, block height, alias, color, version and channel counts. Use lightning_balance_get for balances.

    Inputs

    crypto_codestringrequired
    The cryptoCode of the lightning-node to query. Example: BTC.
    store_idstringrequired
    The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.