Voltage API
Use Voltage API in developer contexts and Voltage for the product. Older
sources and dashboard labels may say “Payments”; keep exact API identifiers and
UI labels when needed to locate something.
Establish the contract
- Use the bundled OpenAPI contract, including its
embedded guides, as the authority. Its provenance is in
sources.json.
- Use Voltage docs for product/setup context only
where consistent with the contract. Consult
known discrepancies before adapting examples.
- Do not use older Voltage APIs, third-party snippets, or model memory to invent
missing endpoints or behavior. When asked for current information, verify the
live contract and affected docs;
disclose unavailable verification. Do not silently rewrite the installed snapshot.
- If the contract itself documents a gap, expose the limitation. In particular,
do not fabricate a canonical Taproot Asset send request.
Read only what the task needs
| Task |
Reference |
| Understand terminology, funding models, setup, or applicability |
Product model |
| Obtain IDs, configure credentials, execute curl, or switch environment |
Configuration and execution |
| Find any endpoint, auth requirement, payload, filter, or response |
API index, then inspect the exact operation |
| Send, receive, poll, handle errors, inspect balances |
Payment lifecycle |
| USD conversion, processing fees, treasury, swaps |
Specialized flows |
| Verify callbacks, manage deliveries, reconcile payments |
Webhooks |
| Integrate hosted checkout or browser session/stream APIs |
Checkout |
Resolve scripts and references relative to this installed skill directory, not
the user's project. In the commands below, <skill-dir> means that directory:
python3 <skill-dir>/scripts/inspect-operation.py create_payment --part request
python3 <skill-dir>/scripts/inspect-operation.py get_payment --part response
python3 <skill-dir>/scripts/inspect-operation.py --schema Amount
python3 <skill-dir>/scripts/inspect-operation.py --guide Payments --section 'Workflow: pay a known BTC invoice from a USD wallet'
The inspector includes referenced schema definitions and operation-specific
security schemes. Read both constraints and descriptions: runtime prerequisites
are not all expressible in JSON Schema. The unmodified source guides may contain
upstream relative links; those are not local skill files.
Integrate or execute
- Establish organization, environment, wallet, network, currency, and the intended
action. Reuse configured values and prior user authorization. Ask only for missing
details that affect correctness or authorization. Do not pick a wallet arbitrarily.
- For ordinary account access use an environment key in
x-api-key. Check each
operation's security contract; checkout browser tokens are different credentials.
- Generate and persist UUIDv4 IDs before submitting payments. Empty
202 means
accepted, not paid. Use bounded reads to wait for the needed state; reconcile
ambiguous writes by the existing ID rather than blindly retrying or creating a new ID.
- Use integer base units: BTC millisatoshis, USD cents, assets their base units.
For generated JavaScript, reject values outside the safe-integer range or use a
lossless JSON strategy; the API's int64 range exceeds JavaScript's safe integers.
- Direct requests are supported through the curl helper.
Read configuration guidance first. It performs one request with no automatic retry,
and supports the environment-API-key operations, not checkout browser transport.
- A balance check authorizes reads; an invoice request authorizes that receive;
a send requires an authorized destination, amount, wallet, and understood fees.
Resolve consequential ambiguity before execution. Do not require repeat approval
for actions already authorized. A connectivity check alone does not authorize spending.
- Before test payments, verify the wallet's network and environment. A label such
as “staging” does not prove test funds. Do not silently fall back to mainnet.
- Keep secrets server-side and out of chat, logs, version control, and browser code.
Webhook creation/rotation returns a one-time secret: arrange secure output before
executing it. Preserve customer defaults when using one-off configuration overrides.
For application code, adapt voltage-client.ts for
bounded payment polling and verify-webhook.ts for raw-body
signature verification. These are focused examples, not a full SDK. Inspect the
operation and response schemas when extending them.
Report the HTTP outcome separately from the business outcome, include relevant
non-secret resource IDs, and state whether a payment completed, failed, is still
pending, or has an uncertain submission outcome. Never label an invoice as paid
because it was generated or a webhook delivery succeeded.
1---2name: voltage-api3description: Build integrations and operate the Voltage API, including wallets, Lightning and on-chain payments, USD quotes, webhooks, balances, and hosted checkout. Use for Voltage product questions, API code, curl requests, and payment debugging. Does not cover the separate Infrastructure API or direct LND administration.4---56# Voltage API78Use **Voltage API** in developer contexts and **Voltage** for the product. Older9sources and dashboard labels may say “Payments”; keep exact API identifiers and10UI labels when needed to locate something.1112## Establish the contract13141. Use the bundled [OpenAPI contract](references/openapi.json), including its15 embedded guides, as the authority. Its provenance is in16 [sources.json](references/sources.json).172. Use [Voltage docs](https://docs.voltageapi.com/) for product/setup context only18 where consistent with the contract. Consult19 [known discrepancies](references/known-discrepancies.md) before adapting examples.203. Do not use older Voltage APIs, third-party snippets, or model memory to invent21 missing endpoints or behavior. When asked for current information, verify the22 live [contract](https://voltageapi.com/v1/openapi/docs.json) and affected docs;23 disclose unavailable verification. Do not silently rewrite the installed snapshot.244. If the contract itself documents a gap, expose the limitation. In particular,25 do not fabricate a canonical Taproot Asset send request.2627## Read only what the task needs2829| Task | Reference |30|---|---|31| Understand terminology, funding models, setup, or applicability | [Product model](references/product-model.md) |32| Obtain IDs, configure credentials, execute curl, or switch environment | [Configuration and execution](references/configuration.md) |33| Find any endpoint, auth requirement, payload, filter, or response | [API index](references/api-index.md), then inspect the exact operation |34| Send, receive, poll, handle errors, inspect balances | [Payment lifecycle](references/payment-lifecycle.md) |35| USD conversion, processing fees, treasury, swaps | [Specialized flows](references/specialized-flows.md) |36| Verify callbacks, manage deliveries, reconcile payments | [Webhooks](references/webhooks.md) |37| Integrate hosted checkout or browser session/stream APIs | [Checkout](references/checkout.md) |3839Resolve scripts and references relative to **this installed skill directory**, not40the user's project. In the commands below, `<skill-dir>` means that directory:4142```sh43python3 <skill-dir>/scripts/inspect-operation.py create_payment --part request44python3 <skill-dir>/scripts/inspect-operation.py get_payment --part response45python3 <skill-dir>/scripts/inspect-operation.py --schema Amount46python3 <skill-dir>/scripts/inspect-operation.py --guide Payments --section 'Workflow: pay a known BTC invoice from a USD wallet'47```4849The inspector includes referenced schema definitions and operation-specific50security schemes. Read both constraints and descriptions: runtime prerequisites51are not all expressible in JSON Schema. The unmodified source guides may contain52upstream relative links; those are not local skill files.5354## Integrate or execute5556- Establish organization, environment, wallet, network, currency, and the intended57 action. Reuse configured values and prior user authorization. Ask only for missing58 details that affect correctness or authorization. Do not pick a wallet arbitrarily.59- For ordinary account access use an environment key in `x-api-key`. Check each60 operation's security contract; checkout browser tokens are different credentials.61- Generate and persist UUIDv4 IDs before submitting payments. Empty `202` means62 accepted, not paid. Use bounded reads to wait for the needed state; reconcile63 ambiguous writes by the existing ID rather than blindly retrying or creating a new ID.64- Use integer base units: BTC millisatoshis, USD cents, assets their base units.65 For generated JavaScript, reject values outside the safe-integer range or use a66 lossless JSON strategy; the API's int64 range exceeds JavaScript's safe integers.67- Direct requests are supported through the [curl helper](scripts/request.py).68 Read configuration guidance first. It performs one request with no automatic retry,69 and supports the environment-API-key operations, not checkout browser transport.70- A balance check authorizes reads; an invoice request authorizes that receive;71 a send requires an authorized destination, amount, wallet, and understood fees.72 Resolve consequential ambiguity before execution. Do not require repeat approval73 for actions already authorized. A connectivity check alone does not authorize spending.74- Before test payments, verify the wallet's network and environment. A label such75 as “staging” does not prove test funds. Do not silently fall back to mainnet.76- Keep secrets server-side and out of chat, logs, version control, and browser code.77 Webhook creation/rotation returns a one-time secret: arrange secure output before78 executing it. Preserve customer defaults when using one-off configuration overrides.7980For application code, adapt [voltage-client.ts](assets/voltage-client.ts) for81bounded payment polling and [verify-webhook.ts](assets/verify-webhook.ts) for raw-body82signature verification. These are focused examples, not a full SDK. Inspect the83operation and response schemas when extending them.8485Report the HTTP outcome separately from the business outcome, include relevant86non-secret resource IDs, and state whether a payment completed, failed, is still87pending, or has an uncertain submission outcome. Never label an invoice as paid88because it was generated or a webhook delivery succeeded.
voltagecloud