Nodes API

All node operations live under the node root. Queries read your team's deployed nodes; mutations are gated to master accounts and require the dashboard Bearer token.

Authorization: Bearer $AMBOSS_DASHBOARD_TOKEN

Queries

node.deployed_nodes

Returns every node owned by your team, ordered by created_at desc.

query DeployedNodes {
  node {
    id
    deployed_nodes {
      id
      alias
      pubkey
      state
      type
      node_type
      network
      is_automated
      taproot_assets_enabled
      created_at
      deactivation_initiated
      deleted_at
    }
  }
}

curl -X POST https://rails.amboss.tech/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AMBOSS_DASHBOARD_TOKEN" \
  -d '{"query":"query{ node { deployed_nodes { id alias pubkey state type } } }"}'

const data = await client.request(DEPLOYED_NODES);
console.log(data.node.deployed_nodes);

node.deployed_node

Fetch a single node by ID. Throws Node not found! if the node does not belong to your team.

query DeployedNode($nodeId: String!) {
  node {
    id
    deployed_node(node_id: $nodeId) {
      id
      pubkey
      alias
      state
      type
      node_type
      network
      is_automated
      taproot_assets_enabled
      withdrawal_target
      funds_available_at
      backup { id created_at size }
      sockets {
        lnd  { id rest grpc }
        litd { id rest grpc }
      }
    }
  }
}

DeployedNode fields

Mutations

node.deploy

Creates a Fully Managed node. The deploy is async: the call returns immediately, RabbitMQ provisions the node in the background, and the node advances through CREATED → WAITING_FOR_CREDENTIALS → WAITING_FOR_DEPOSIT once the dashboard finishes the credential setup.

mutation Deploy($type: String) {
  node {
    deploy(type: $type) {
      success
    }
  }
}

deploy(type: PAYMENTS) additionally requires a live Payments environment to already exist (Set up a live payments environment before deploying a payments node).

node.connect

Attaches Rails to a Lightning node you already operate. Supply either an lnd or litd credential block.

mutation Connect($input: NodeConnectInput!) {
  node {
    connect(input: $input) {
      node_id
      success
    }
  }
}

Variables:

{
  "input": {
    "node_type": "LP",
    "lnd": {
      "rest": "https://your-lnd:8080",
      "grpc": "your-lnd:10009",
      "tls_cert": "-----BEGIN CERTIFICATE-----\n...",
      "management_macaroon": "<hex-encoded admin-equivalent macaroon>"
    }
  }
}

For Litd:

{
  "input": {
    "node_type": "LP",
    "litd": {
      "rest": "https://your-litd:8443",
      "grpc": "your-litd:10009",
      "tls_cert": null,
      "management_macaroon": "<hex>",
      "taproot_assets": true
    }
  }
}

The macaroon must include the Required permissions (view, channel management, fee policy, invoice creation). Rails encrypts and stores the macaroon; the raw value never leaves your network in cleartext on the response.

node.activate

Flips a node from WAITING_FOR_ACTIVATION to ACTIVE. Returns a Stripe checkout URL the user must complete to set up the subscription.

mutation Activate($nodeId: String!, $successUrl: String!, $cancelUrl: String!) {
  node {
    activate(node_id: $nodeId, success_url: $successUrl, cancel_url: $cancelUrl) {
      success
      external_url
    }
  }
}

success_url and cancel_url are the URLs Stripe redirects to after checkout. If the user returns to success_url, the node automation flips on automatically (driven by the Stripe webhook).

external_url is null when no subscription is needed (team accounts, non-mainnet networks, the RAILS_WITHOUT_SUB user tag).

node.deactivate

Begin offboarding. Channels close, funds unwind, and the node moves through DELETION_INITIATED → DELETED. Requires the master-account password hash for irreversibility.

mutation Deactivate($input: NodeDeactivationInput!) {
  node {
    deactivate(input: $input) {
      success
    }
  }
}

{
  "input": {
    "node_id": "<NODE_ID>",
    "password_hash": "<argon2id-derived hash, see Security>"
  }
}

See Security for how to derive the password hash client-side.

node.change_settings

Update node settings such as the Lightning alias. Currently supported on Fully Managed nodes only and rate-limited to one change per 24 hours.

mutation ChangeSettings($input: NodeSettingsInput!) {
  node {
    change_settings(input: $input) {
      new_alias
    }
  }
}

{ "input": { "node_id": "<NODE_ID>", "alias": "treasury-lp-01" } }

Related namespaces

• node.withdrawal.* - see Withdraw
• node.asset.* - see Assets
• node.partners.* - peer/partner-list management (not covered here; see Apollo Studio)
• node.invoices.* - generate node-side invoices (not covered here; use the LND macaroon for direct invoice creation if needed)