# 0neshot101/btcpay-js architecture

> Architecture diagram of the GitHub repository 0neshot101/btcpay-js, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0neshot101/btcpay-js
- Repository: https://github.com/0neshot101/btcpay-js

## Overview

BTCPay-JS is a typed TypeScript client for BTCPay Server’s REST API. An application configures `BTCPayClient`, chooses a resource client (including store-scoped invoices), and makes an operation that the shared HTTP client sends to the server and returns as a typed response. Resource clients cover the documented store, payment, wallet, Lightning, app, notification, webhook, user, API-key, server and file capabilities. Sampled code confirms construction and HTTP behavior; several resource-to-transport calls are documented by the README but their source excerpts were not shown.

Main entry points: [`src/client.ts`](https://github.com/0neshot101/btcpay-js/blob/main/src/client.ts) (BTCPayClient), [`src/utils/http-client.ts`](https://github.com/0neshot101/btcpay-js/blob/main/src/utils/http-client.ts) (HTTP client), [`src/structures/apps.ts`](https://github.com/0neshot101/btcpay-js/blob/main/src/structures/apps.ts) (Apps), [`src/structures/webhooks.ts`](https://github.com/0neshot101/btcpay-js/blob/main/src/structures/webhooks.ts) (Webhooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client entry"]
  node_client["BTCPayClient<br/>[client.ts]"]
end

subgraph group_resources["API resources"]
  node_stores["Stores<br/>[stores.ts]"]
  node_invoices["Invoices<br/>[invoices.ts]"]
  node_pull["Pull payments<br/>[pull-payments.ts]"]
  node_lightning["Lightning<br/>[lightning.ts]"]
  node_addresses["Lightning addresses"]
  node_methods["Payment methods<br/>[payment-methods.ts]"]
  node_apps["Apps<br/>[apps.ts]"]
  node_notifications["Notifications<br/>[notifications.ts]"]
  node_webhooks["Webhooks<br/>[webhooks.ts]"]
  node_serverfiles["Server and files<br/>[server.ts]"]
  node_users["Users<br/>[users.ts]"]
  node_keys["API keys<br/>[api-keys.ts]"]
  node_requests["Payment requests"]
end

subgraph group_transport["HTTP transport"]
  node_http["HTTP client<br/>[http-client.ts]"]
end

subgraph group_contracts["Types and errors"]
  node_errorhandling["API errors<br/>[errors.ts]"]
  node_common["Shared API types<br/>[common.ts]"]
  node_invoicecontracts["Invoice types<br/>[invoices.ts]"]
  node_lightningcontracts["Lightning types<br/>[lightning.ts]"]
  node_paymentcontracts["Payment method types<br/>[payment-methods.ts]"]
  node_pullcontracts["Payout types<br/>[pull-payments.ts]"]
  node_appcontracts["App types<br/>[apps.ts]"]
end

node_caller(("SDK consumer"))

node_caller -->|"configures"| node_client
node_client -->|"creates"| node_stores
node_client -->|"creates"| node_invoices
node_client -->|"creates"| node_pull
node_client -->|"creates"| node_lightning
node_client -->|"creates"| node_addresses
node_client -->|"creates"| node_methods
node_client -->|"creates"| node_apps
node_client -->|"creates"| node_notifications
node_client -->|"creates"| node_webhooks
node_client -->|"creates"| node_serverfiles
node_client -->|"creates"| node_users
node_client -->|"creates"| node_keys
node_client -->|"creates"| node_requests
node_client -->|"creates"| node_http
node_apps -->|"sends requests"| node_http
node_webhooks -->|"sends requests"| node_http
node_http -->|"raises errors"| node_errorhandling
node_apps -->|"uses types"| node_appcontracts
node_invoices -.->|"uses types"| node_invoicecontracts
node_lightning -.->|"uses types"| node_lightningcontracts
node_methods -.->|"uses types"| node_paymentcontracts
node_pull -.->|"uses types"| node_pullcontracts
node_webhooks -->|"uses identifiers"| node_common

click node_client "https://github.com/0neshot101/btcpay-js/blob/main/src/client.ts"
click node_stores "https://github.com/0neshot101/btcpay-js/blob/main/src/structures/stores.ts"
click node_invoices "https://github.com/0neshot101/btcpay-js/blob/main/src/structures/invoices.ts"
click node_pull "https://github.com/0neshot101/btcpay-js/blob/main/src/structures/pull-payments.ts"
click node_lightning "https://github.com/0neshot101/btcpay-js/blob/main/src/structures/lightning.ts"
click node_addresses "https://github.com/0neshot101/btcpay-js/blob/main/src/structures/lightning-addresses.ts"
click node_methods "https://github.com/0neshot101/btcpay-js/blob/main/src/structures/payment-methods.ts"
click node_apps "https://github.com/0neshot101/btcpay-js/blob/main/src/structures/apps.ts"
click node_notifications "https://github.com/0neshot101/btcpay-js/blob/main/src/structures/notifications.ts"
click node_webhooks "https://github.com/0neshot101/btcpay-js/blob/main/src/structures/webhooks.ts"
click node_serverfiles "https://github.com/0neshot101/btcpay-js/blob/main/src/structures/server.ts"
click node_users "https://github.com/0neshot101/btcpay-js/blob/main/src/structures/users.ts"
click node_keys "https://github.com/0neshot101/btcpay-js/blob/main/src/structures/api-keys.ts"
click node_requests "https://github.com/0neshot101/btcpay-js/blob/main/src/structures/payment-requests.ts"
click node_http "https://github.com/0neshot101/btcpay-js/blob/main/src/utils/http-client.ts"
click node_errorhandling "https://github.com/0neshot101/btcpay-js/blob/main/src/utils/errors.ts"
click node_common "https://github.com/0neshot101/btcpay-js/blob/main/src/typings/common.ts"
click node_invoicecontracts "https://github.com/0neshot101/btcpay-js/blob/main/src/typings/invoices.ts"
click node_lightningcontracts "https://github.com/0neshot101/btcpay-js/blob/main/src/typings/lightning.ts"
click node_paymentcontracts "https://github.com/0neshot101/btcpay-js/blob/main/src/typings/payment-methods.ts"
click node_pullcontracts "https://github.com/0neshot101/btcpay-js/blob/main/src/typings/pull-payments.ts"
click node_appcontracts "https://github.com/0neshot101/btcpay-js/blob/main/src/typings/apps.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client toneBlue
class node_stores,node_invoices,node_pull,node_lightning,node_addresses,node_methods,node_apps,node_notifications,node_webhooks,node_serverfiles,node_users,node_keys,node_requests toneAmber
class node_http toneMint
class node_errorhandling,node_common,node_invoicecontracts,node_lightningcontracts,node_paymentcontracts,node_pullcontracts,node_appcontracts toneRose
class node_caller toneIndigo
```

## Components

### Client entry

- [BTCPayClient](https://github.com/0neshot101/btcpay-js/blob/main/src/client.ts): `src/client.ts`

### API resources

- [Stores](https://github.com/0neshot101/btcpay-js/blob/main/src/structures/stores.ts): `src/structures/stores.ts`
- [Invoices](https://github.com/0neshot101/btcpay-js/blob/main/src/structures/invoices.ts): `src/structures/invoices.ts`
- [Pull payments](https://github.com/0neshot101/btcpay-js/blob/main/src/structures/pull-payments.ts): `src/structures/pull-payments.ts`
- [Lightning](https://github.com/0neshot101/btcpay-js/blob/main/src/structures/lightning.ts): `src/structures/lightning.ts`
- [Lightning addresses](https://github.com/0neshot101/btcpay-js/blob/main/src/structures/lightning-addresses.ts): `src/structures/lightning-addresses.ts`
- [Payment methods](https://github.com/0neshot101/btcpay-js/blob/main/src/structures/payment-methods.ts): `src/structures/payment-methods.ts`
- [Apps](https://github.com/0neshot101/btcpay-js/blob/main/src/structures/apps.ts): `src/structures/apps.ts`
- [Notifications](https://github.com/0neshot101/btcpay-js/blob/main/src/structures/notifications.ts): `src/structures/notifications.ts`
- [Webhooks](https://github.com/0neshot101/btcpay-js/blob/main/src/structures/webhooks.ts): `src/structures/webhooks.ts`
- [Server and files](https://github.com/0neshot101/btcpay-js/blob/main/src/structures/server.ts): `src/structures/server.ts`
- [Users](https://github.com/0neshot101/btcpay-js/blob/main/src/structures/users.ts): `src/structures/users.ts`
- [API keys](https://github.com/0neshot101/btcpay-js/blob/main/src/structures/api-keys.ts): `src/structures/api-keys.ts`
- [Payment requests](https://github.com/0neshot101/btcpay-js/blob/main/src/structures/payment-requests.ts): `src/structures/payment-requests.ts`

### HTTP transport

- [HTTP client](https://github.com/0neshot101/btcpay-js/blob/main/src/utils/http-client.ts): `src/utils/http-client.ts`

### Types and errors

- [API errors](https://github.com/0neshot101/btcpay-js/blob/main/src/utils/errors.ts): `src/utils/errors.ts`
- [Shared API types](https://github.com/0neshot101/btcpay-js/blob/main/src/typings/common.ts): `src/typings/common.ts`
- [Invoice types](https://github.com/0neshot101/btcpay-js/blob/main/src/typings/invoices.ts): `src/typings/invoices.ts`
- [Lightning types](https://github.com/0neshot101/btcpay-js/blob/main/src/typings/lightning.ts): `src/typings/lightning.ts`
- [Payment method types](https://github.com/0neshot101/btcpay-js/blob/main/src/typings/payment-methods.ts): `src/typings/payment-methods.ts`
- [Payout types](https://github.com/0neshot101/btcpay-js/blob/main/src/typings/pull-payments.ts): `src/typings/pull-payments.ts`
- [App types](https://github.com/0neshot101/btcpay-js/blob/main/src/typings/apps.ts): `src/typings/apps.ts`

### Other components

- **SDK consumer**

## Connections

- SDK consumer → BTCPayClient: configures (evidence: `README.md`)
- BTCPayClient → Stores: creates (evidence: `src/client.ts`)
- BTCPayClient → Invoices: creates (evidence: `src/client.ts`)
- BTCPayClient → Pull payments: creates (evidence: `src/client.ts`)
- BTCPayClient → Lightning: creates (evidence: `src/client.ts`)
- BTCPayClient → Lightning addresses: creates (evidence: `src/client.ts`)
- BTCPayClient → Payment methods: creates (evidence: `src/client.ts`)
- BTCPayClient → Apps: creates (evidence: `src/client.ts`)
- BTCPayClient → Notifications: creates (evidence: `src/client.ts`)
- BTCPayClient → Webhooks: creates (evidence: `src/client.ts`)
- BTCPayClient → Server and files: creates (evidence: `src/client.ts`)
- BTCPayClient → Users: creates (evidence: `src/client.ts`)
- BTCPayClient → API keys: creates (evidence: `src/client.ts`)
- BTCPayClient → Payment requests: creates (evidence: `src/client.ts`)
- BTCPayClient → HTTP client: creates (evidence: `src/client.ts`)
- Apps → HTTP client: sends requests (evidence: `src/structures/apps.ts`)
- Webhooks → HTTP client: sends requests (evidence: `src/structures/webhooks.ts`)
- HTTP client → API errors: raises errors (evidence: `src/utils/http-client.ts`)
- Apps → App types: uses types (evidence: `src/structures/apps.ts`)
- Invoices → Invoice types: uses types
- Lightning → Lightning types: uses types
- Payment methods → Payment method types: uses types
- Pull payments → Payout types: uses types
- Webhooks → Shared API types: uses identifiers (evidence: `src/structures/webhooks.ts`)
