Channel node API

The owner's API of a payment channel node (docs/CHANNELD.md). Every /v1 route requires Authorization: Bearer <ARREKTA_CHANNELD_API_TOKEN>; /healthz and /metrics (Prometheus) do not. Amounts are decimal strings in base units. Errors are RFC 9457 problem documents. Keep this API private: it moves money.

Default base URL http://127.0.0.1:9737. SDKs: createChanneldClient (TypeScript), ChanneldClient (Python). Design: Channel node.

Endpoints

GET /v1/info

Node identity, network, tip and counts.

curl -s -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/info

Response 200: NodeInfo

GET /v1/wallet

On-chain wallet addresses and balances. Fund the receive address to open channels and to pay close and sweep fees.

curl -s -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/wallet

Response 200: Wallet

GET /v1/peers

Connected peers.

curl -s -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/peers

Response 200: object

POST /v1/peers

Connect to a channel node. Dials address over the post-quantum transport; node_id, when given, must match the peer's proven identity.

curl -s -X POST -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/peers -H 'content-type: application/json' -d '{…}'

Request body

Response 200: object

GET /v1/channels

All channels, newest first.

curl -s -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/channels

Response 200: object

POST /v1/channels

Open a channel. Funds the channel from the wallet and returns once the peer has signed our first commitment and the funding transaction is broadcast. The channel becomes active after min_depth confirmations.

curl -s -X POST -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/channels -H 'content-type: application/json' -d '{…}'

Request body

Response 201: Channel

GET /v1/channels/{id}

One channel.

curl -s -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/channels/<id>

Response 200: Channel

POST /v1/channels/{id}/close

Close a channel. Cooperative by default: no new HTLCs, then a zero-fee close confirmed by CPFP once pending HTLCs settle. force broadcasts our latest commitment; our balance then waits to_self_delay blocks.

curl -s -X POST -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/channels/<id>/close -H 'content-type: application/json' -d '{…}'

Request body

Response 200: Channel

POST /v1/channels/{id}/splice

Splice a channel in or out. Changes the capacity without closing: a positive amount adds coins from the node's wallet, a negative one pays out to address (default: the node's wallet). ARRK channels only. The channel must be quiet (no HTLCs); it pauses payments until the splice transaction is min_depth deep and both sides lock it.

curl -s -X POST -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/channels/<id>/splice -H 'content-type: application/json' -d '{…}'

Request body

Response 200: Channel

GET /v1/invoices

Invoices we issued.

curl -s -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/invoices

Response 200: object

POST /v1/invoices

Create an invoice. Route hints for our private channels are added automatically.

curl -s -X POST -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/invoices -H 'content-type: application/json' -d '{…}'

Request body

Response 201: Invoice

POST /v1/invoices/decode

Decode and verify a arrektapay: invoice.

curl -s -X POST -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/invoices/decode -H 'content-type: application/json' -d '{…}'

Request body

Response 200: DecodedInvoice

GET /v1/invoices/{hash}

Invoice status.

curl -s -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/invoices/<hash>

Response 200: Invoice

GET /v1/payments

Payments we sent.

curl -s -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/payments

Response 200: object

POST /v1/payments

Pay an invoice. Finds a route, sends, and retries around failures until it succeeds, fails for good, or timeout_secs passes. On timeout the payment may still complete: poll /v1/payments/{hash}. preimage is the proof of payment.

curl -s -X POST -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/payments -H 'content-type: application/json' -d '{…}'

Request body

Response 200: Payment

GET /v1/payments/{hash}

Payment status and attempts.

curl -s -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/payments/<hash>

Response 200: Payment

POST /v1/routes

Preview the route and fee for an invoice.

curl -s -X POST -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/routes -H 'content-type: application/json' -d '{…}'

Request body

Response 200: Route

GET /v1/graph

Public channels and nodes.

curl -s -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/graph

Response 200: object

GET /v1/tower

Watchtower server and client status.

curl -s -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/v1/tower

Response 200: object

GET /public/v1/graph

Public channel graph: totals, nodes, open channels, and the 20 most recent closed ones (closed, closed_count) (no token; ARREKTA_CHANNELD_PUBLIC_GRAPH=true). What gossip already announces, for explorers. CORS allows any origin.

curl -s -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/public/v1/graph

Response 200: object

GET /public/v1/channels/{id}

One public channel (by its funding-output id): status open, or closed with its closing transaction and the later spends of its outputs.

curl -s -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/public/v1/channels/<id>

Response 200: object

GET /public/v1/nodes/{id}

One public node, its open channels (channel_list) and its closed ones (closed_list).

curl -s -H "authorization: Bearer $TOKEN" http://127.0.0.1:9737/public/v1/nodes/<id>

Response 200: object

Schemas

Problem

RFC 9457 problem details.

NodeInfo

Wallet

Peer

Htlc

Channel

Invoice

DecodedInvoice

Attempt

Payment

Route