> For the complete documentation index, see [llms.txt](https://www.webln.guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.webln.guide/building-lightning-apps/getting-started.md).

# 👨💻 Getting Started

### Installation

Browsers with WebLN capabilities provide APIs using a global JavaScript variable `window.webln` that can be used to interact with the connected Bitcoin Lightning wallet. 

{% content-ref url="/pages/PyPNrgZehYH8gbxnJo6v" %}
[WebLN Providers](/ressources/webln-providers.md)
{% endcontent-ref %}

**You don't need to add any library to your project.**

### Detecting WebLN support

Before you start using WebLN you need to check for browser support by checking if the variable `window.webln` is defined:

```javascript
if (typeof window.webln !== 'undefined') {
  console.log('WebLN is available!');
}
```

{% hint style="warning" %}
`window.webln` might not be available during pageload. See the code example below for proper detection.
{% endhint %}

<details>

<summary>Detect if a WebLN provider is available</summary>

```javascript
async function detectWebLNProvider(timeoutParam) {
  const timeout = timeoutParam ?? 3000;
  const interval = 100;
  let handled = false;

  return new Promise((resolve) => {
    if (window.webln) {
      handleWebLN();
    } else {
      document.addEventListener("webln:ready", handleWebLN, { once: true });
      
      let i = 0;
      const checkInterval = setInterval(function() {
        if (window.webln || i >= timeout/interval) {
          handleWebLN();
          clearInterval(checkInterval);
        }
        i++;
      }, interval);
    }

    function handleWebLN() {
      if (handled) {
        return;
      }
      handled = true;

      document.removeEventListener("webln:ready", handleWebLN);

      if (window.webln) {
        resolve(window.webln);
      } else {
        resolve(null);
      }
    }
  });
}
```

</details>

### Enable WebLN <a href="#connecting-to-metamask" id="connecting-to-metamask"></a>

Before you can work with any of the WebLN APIs you need call the method `enable()` :

```typescript
await window.webln.enable();
```

Depending on the used WebLN provider this will ask the user to connect their Lightning wallet with the website.&#x20;

![The WebLN provider will ask the user for permission to connect with your website.](/files/a0CWBSysFNnyKNcFAFX0)

{% hint style="info" %}
You should only initiate a request in response to direct user action, such as clicking a button.
{% endhint %}

### Using WebLN

Now you are ready to work with the WebLN APIs.&#x20;

```javascript
await window.webln.enable();
await window.webln.sendPayment();
```

Have a look at the the [WebLN Reference](/building-lightning-apps/webln-reference.md) for detailed explanations and usage examples for the different APIs.

### WebLN Events

WebLN triggers events like `webln:enabled` upon enabling, allowing apps and packages to subscribe and listen to these events.

```javascript
window.addEventListener("webln:enabled", () => {
    console.log("WebLN is enabled!");
});
```

### Error handling

There are different errors that can happen while using the WebLN APIs. Make sure to handle them and let the user know what went wrong.

{% content-ref url="/pages/IcCnXHwSFAbpmNupGqXp" %}
[Error handling](/building-lightning-apps/webln-reference/error-handling.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://www.webln.guide/building-lightning-apps/getting-started.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.