# Build with AI

Give your coding assistant the same documentation you use. This guide provides a focused integration brief, plain-text references and boundaries that keep generated code aligned with SatLane's current API.

## Choose your context

Start with the [quickstart](/docs/quickstart), [invoice guide](/docs/invoices) and [webhook guide](/docs/webhooks). For a complete reference, download the [integration manual](/docs/integration.md). The [plain-text index](/llms.txt) links the Markdown versions of individual guides. A [combined context file](/llms-full.txt) is available when your assistant needs the complete manual and this brief together.

These files are generated from the same sources as the website. They help you provide accurate context; they do not guarantee that every AI service automatically reads the website.

## Copy the integration brief

Replace the bracketed values with your project's details. Keep actual secrets in environment variables. Do not paste API keys, wallet private keys, signing secrets or customer data into a prompt.

```text
Help me integrate SatLane into [framework and runtime].

My documentation origin: https://www.satlane.com
[Replace this with your documentation origin for a self-hosted installation.]
Read /docs/quickstart.md, /docs/invoices.md,
/docs/webhooks.md, /docs/checkout.md, /docs/test-mode.md
and /docs/errors.md from that origin before writing code.
Read /docs/statuses.md for split payments and /docs/billing.md
for due bills and Live creation locks.

Goal: [describe the payment and order flow].
My order storage and durable job queue: [describe them].
Checkout choice: [hosted checkout or custom UI].

Confirm the installation mode and API origin first.
Use https://api.satlane.com for the public API, or the
configured origin of my self-hosted installation. Handle
contract compatibility errors; do not infer enabled features.
Create invoices server-side using Authorization: Bearer
and a secret environment variable. Never expose the API key
in browser code. Send a unique Idempotency-Key for each
logical create. Retry sequentially with the same key/body.
Enabled creation reserves scoped keys and commits invoice
and replay response atomically. Legacy installs provide
sequential response replay. Still reconcile at order level.

Configure a store webhook endpoint in the dashboard for
the invoice environment. Use a public HTTPS receiver or
an HTTPS tunnel to a local handler; remote SatLane cannot
reach your localhost. callback_url is stored metadata
and does not replace registered destinations.

On enabled installs, start in Sandbox with a test API key.
Send SatLane-Version: 2026-10-05 for Test invoice creation.
Require environment=test, address=null, payment_uri=null
and a simulated payment_destination. No xpub is needed.
Do not invent a QR code or wallet link for simulated funds.
If the contract is unavailable, stop and confirm whether
the installation uses legacy test_mode rules.
Live requires explicit activation and a mainnet wallet;
workspace switching alone does not enable payments.

Use invoice.hosted_checkout_url for the hosted flow.
For custom checkout, read the public invoice snapshot,
listen to EventSource.onmessage and inspect event_type.
Refetch after reconnecting; do not assume event replay.
Close live connections when the component unmounts.

Verify webhooks using the original raw request body,
HMAC-SHA256 and the timestamp tolerance. Configure the
raw-body route before a JSON body parser. Compare
signatures safely and reject invalid payloads.

Persist event_id with a unique constraint and queue
processing atomically before acknowledging with 2xx.
Repeated valid deliveries must also receive 2xx.
Check order, amount, currency and environment before
fulfillment. Browser redirects and SSE are UI signals,
not authorization to ship an order. Plan for late payments,
top-ups with mixed confirmation counts, overpayments,
review states and reversals. amount_paid_sats is received
Bitcoin, not confirmed coverage. A full received balance
should show confirming, never a request to pay twice.

Use only documented endpoints and response fields.
Do not invent SDK installs, strict environment rejections,
callback delivery, global rate caps or exactly-once events.
Separate runnable code from illustrative pseudocode.
Ask me for missing order-policy decisions.

Provide implementation, focused tests, environment-variable
names, dashboard setup steps and the remaining decisions.
Keep credentials out of source control and test fixtures.
```

## Verify the generated integration

Test a successful invoice, invalid signature, repeated webhook, underpayment with a top-up, an expired invoice, a late payment, a reversed payment and a temporary API failure. Confirm that repeated notifications do not fulfill an order twice. Treat test and live environments separately.

Do not ship an example handler that acknowledges a webhook before durable storage. The guide's minimal handler is a teaching skeleton; your application still needs persistence, queueing and order reconciliation.

## Current integration boundaries

- The public invoice API uses API keys. Store webhook management is a dashboard/session operation with required verification.
- Enabled Sandbox creates wallet-free Test invoices with the version header; Live uses explicit activation and a mainnet receiving wallet. Disabled installations retain legacy test_mode and receiving-wallet rules. Confirm the mode before integration.
- For local or self-hosted use, confirm that chain services and the watcher are running before testing real Live settlement. A working Sandbox does not prove Live chain connectivity.
- Invoice creation has a configured 100 requests/minute cap with the current IP-based bucket. Honor `error.details.retry_after_seconds` on 429 rather than inventing other limits.
- SSE emits ordinary message frames. The JSON event payload differs from the signed webhook envelope.
- No public npm installation of `@satlane/webhooks` is required by these guides. The Node.js example uses built-in crypto.
- No OpenAPI document or hosted AI agent is provided by this page. Plain-text documentation is context for your own assistant.

## Keep the context current

Refetch these references when changing an integration. If a response differs from a guide, stop and inspect the actual response before inferring an undocumented guarantee. Contact [support@satlane.com](mailto:support@satlane.com) with a request ID when one is available, without including secrets.