PayEngine

Authentication Header

x-api-key: your_api_key_here

Routes that require the header

Read endpoints and POST /users/{id}/withdraw/preview move no funds and do not require the header.

Key format

• 16–128 characters
• Allowed characters: A-Z a-z 0-9 . _ : -
• Sent exactly once per request (a repeated header is rejected)
• A UUID v4 is the recommended default

Keys are scoped per application and per operation, so they never collide with another integrator, and the same value may safely be reused across a tip and a withdrawal.

Replay behaviour

Reuse the exact same key to retry the exact same operation. The server does not move a single millisatoshi a second time: it returns the original movement, flagged with replayed: true.

curl -X POST https://payengine.metronomiq.io/users/user_123/tips \
  -H "x-api-key: your_api_key_here" \
  -H "Idempotency-Key: tip:order-8842" \
  -H "Content-Type: application/json" \
  -d '{"toUserId":"user_456","amount":1000,"currency":"SAT"}'

{
  "transactionId": "transaction-uuid-here",
  "fromUserId": "user_123",
  "toUserId": "user_456",
  "amountMsat": "1000000",
  "appFeeMsat": "100000",
  "status": "SUCCESS",
  "replayed": true
}

Never reuse a key for a different operation. For a withdrawal the server rejects it with 409 IDEMPOTENCY_KEY_REUSED; elsewhere it would treat it as a replay and the second payment would silently never happen. Derive keys from your own business identifiers, for example tip:{orderId}.

Withdrawal deduplication (server-side)

A withdrawal is the only irreversible way funds leave PayEngine, so it carries a second guarantee that does not depend on your key at all: a bolt11 invoice can only ever be paid once. Both guarantees are enforced by the database, so they hold under concurrent requests.

• Same key, same invoice — returns the state of the existing withdrawal with replayed: true, even while payments are paused. status is PENDING while the payment is still in flight, then SUCCESS — or FAILED if it failed and the reservation was refunded.
• Different key, same invoice — rejected with 409 WITHDRAWAL_ALREADY_IN_FLIGHT. Retrying will not help.
• Same key, another user or another invoice — rejected with 409 IDEMPOTENCY_KEY_REUSED. The state of another withdrawal is never returned.
• Failed withdrawal — the reservation was refunded, so the same invoice may legitimately be retried, with a new key. If that retry cannot get a definitive answer from the node, it ends in 504 WITHDRAWAL_OUTCOME_PENDING and may need a manual review.

{
  "transactionId": "transaction-uuid-here",
  "paymentHash": "payment-hash-here",
  "amountMsat": "20000",
  "feeMsat": "1000",
  "totalDebitedMsat": "21000",
  "status": "PENDING",
  "completedAt": null,
  "replayed": true
}

Errors

Upload your RSA public key in PEM format.

Request

{
  "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\n-----END PUBLIC KEY-----"
}

Configure the URL where PayEngine will send webhook notifications.

Request

{
  "url": "https://your-app.com/webhooks/payengine"
}

Generate a new webhook signing secret for security.

{
  "newWebhookSecret": "new_webhook_secret"
}

Create a new user with an internal wallet.

Request

{
  "externalId": "user_123"
}

{
  "id": "user-uuid-here",
  "externalId": "user_123",
  "feePercent": 10,
  "applicationId": "application-uuid-here",
  "walletId": "wallet-uuid-here",
  "kind": "STANDARD"
}

List all users in your application.

[
  {
    "id": "user-uuid-here",
    "externalId": "user_123",
    "feePercent": 10,
    "applicationId": "application-uuid-here",
    "walletId": "wallet-uuid-here",
    "kind": "STANDARD"
  },
  {
    "id": "user-uuid-2-here",
    "externalId": "user_456",
    "feePercent": 15,
    "applicationId": "application-uuid-here",
    "walletId": "wallet-uuid-2-here",
    "kind": "STANDARD"
  }
]

Get a specific user by their external ID.

Path Parameters

id: User external ID (e.g., "user_123")

{
  "id": "user-uuid-here",
  "externalId": "user_123",
  "feePercent": 10,
  "applicationId": "application-uuid-here",
  "walletId": "wallet-uuid-here",
  "kind": "STANDARD"
}

Send a tip from one user to another user.

Path Parameters

id: User external ID of the sender (e.g., "user_123")

Request

{
  "toUserId": "user_456",
  "amount": 1000,
  "currency": "SAT"
}

Request Body Parameters

{
  "transactionId": "transaction-uuid-here",
  "fromUserId": "user_123",
  "toUserId": "user_456",
  "amountMsat": "1000000",
  "appFeeMsat": "100000",
  "status": "SUCCESS"
}

Generate a Lightning invoice for user deposits.

Path Parameters

id: User external ID (e.g., "user_123")

Request

{
  "amount": 1000
}

{
  "id": "deposit-uuid-here",
  "paymentHash": "payment-hash-here",
  "request": "lnbc1000...",
  "amountSat": "1000",
  "amountMsat": "1000000",
  "description": "Deposit for user user_123",
  "status": "PENDING",
  "expiresAt": "2024-01-01T12:30:00Z"
}

Preview fees and check balance before withdrawal.

Path Parameters

id: User external ID (e.g., "user_123")

Request

{
  "invoice": "lnbc1000n1pwg..."
}

{
  "invoiceAmountMsat": "1000000",
  "invoiceAmountSat": "1000",
  "estimatedFeeMsat": "1001",
  "estimatedFeeSat": "1",
  "totalRequiredMsat": "1001001",
  "totalRequiredSat": "1001",
  "currentBalanceMsat": "45900",
  "currentBalanceSat": "45",
  "hasSufficientFunds": false,
  "description": "Payment for services",
  "destination": "02152fe11f478063aab5a324d0c244b268205d1edd577b0bd95f4c935b5ff71966",
  "expiresAt": "2025-09-05T21:35:17.000Z"
}

Pay a Lightning invoice on behalf of a user.

Path Parameters

id: User external ID (e.g., "user_123")

Request

{
  "invoice": "lnbc1000n1pwg..."
}

{
  "paymentHash": "payment-hash-here",
  "amountMsat": "1000000",
  "feeMsat": "1000",
  "totalDebitedMsat": "1001000",
  "estimatedFeeMsat": "800",
  "actualFeeMsat": "1000",
  "confirmedAt": "2024-01-01T12:00:00Z"
}

Where the money is, answer by answer

A withdrawal first reserves the amount plus the estimated network fee on the user's balance, then pays the invoice.

• 200 — paid. The balance was debited by totalDebitedMsat; the unused part of the fee reserve was returned.
• 200 with replayed: true — same Idempotency-Key: the current state of that withdrawal (PENDING, SUCCESS or FAILED).
• 400 INVOICE_EXPIRED, 503 LIGHTNING_UNAVAILABLE — refused before anything was reserved.
• 502 WITHDRAWAL_PAYMENT_FAILED — the node confirmed the failure; the reservation is back on the balance.
• 504 WITHDRAWAL_OUTCOME_PENDING — the outcome is not known yet; the amount stays reserved. Show the user that the withdrawal is being verified, and replay with the same key to follow it.

Check a user's wallet balance.

Path Parameters

id: User external ID (e.g., "user_123")

{
  "balance": {
    "balanceMsat": "5000000",
    "balanceSat": "5000"
  }
}

Renvoie les 50 invoices les plus récentes de l'utilisateur, invoiceRequest (la bolt11) inclus.

Query parameters

curl "https://payengine.metronomiq.io/api/users/user_123/deposit?payableOnly=true" \
  -H "x-api-key: $PAYENGINE_API_KEY"

[
  {
    "id": "invoice-uuid",
    "paymentHash": "a1b2c3…",
    "amountMsat": "500000",
    "invoiceRequest": "lnbc…",
    "description": "Top-up",
    "status": "PENDING",
    "createdAt": "2026-08-10T10:00:00.000Z",
    "expiresAt": "2026-08-10T10:30:00.000Z",
    "isPayable": true
  }
]

isPayable est calculé par le serveur, avec la même horloge que celle qui fera expirer l'invoice. Ne le recalculez pas depuis expiresAt et l'heure du client : sa dérive produirait des faux positifs.

Check the status of a deposit invoice.

Path Parameters

id: User external ID (e.g., "user_123")
paymentHash: Payment hash from deposit invoice

{
  "status": "PAID",
  "amountMsat": "1000000",
  "amountSat": "1000",
  "description": "Deposit for user user_123",
  "expiresAt": "2024-01-01T12:30:00Z",
  "createdAt": "2024-01-01T12:00:00Z",
  "walletId": "wallet-uuid-here"
}

{
  "status": "EXPIRED",
  "amountMsat": "1000000",
  "expiresAt": "2024-01-01T12:30:00Z"
}

EXPIRED is not always final: a payment accepted by the node just before expiry can settle shortly after it. Such an invoice is still credited — exactly once — and its status becomes PAID. Keep polling for about an hour after expiry if the user says they paid.

{
  "status": "NOT_FOUND"
}

Update a user's external ID.

Path Parameters

id: Current user external ID (e.g., "user_123")

Request

{
  "updatedExternalId": "user_456", //optional
  "feePercent": 10, //optional
  "tipFeePercent": 10 //optional
}

{
  "id": "user-uuid-here",
  "externalId": "user_456",
  "feePercent": 10,
  "applicationId": "application-uuid-here",
  "walletId": "wallet-uuid-here",
  "kind": "STANDARD"
}

Create a payment policy: the price of one step, the rhythm, the beneficiary and, optionally, the owner.

Parameters

Request

{
  "externalUserId": "user_123",
  "externalOwnerId": "user_456",
  "name": "policy_premium_video",
  "amount": 1,
  "stepValue": 5,
  "stepUnitKeyName": "SECONDS"
}

{
  "id": "policy-uuid-here",
  "userId": "user-uuid-here",
  "ownerId": "owner-uuid-here",
  "name": "policy_premium_video",
  "amountMsat": "1000",
  "stepValue": 5,
  "currency": "SATS",
  "stepUnitId": "step-unit-uuid-here",
  "createdAt": "2024-01-01T12:00:00Z"
}

404 USER_NOT_FOUND when the beneficiary or the owner does not exist in your application — details.field says which (externalUserId or externalOwnerId). 400 USER_RESERVED for a reserved identifier, 400 STEP_UNIT_NOT_FOUND for an unknown stepUnitKeyName, 400 VALIDATION_ERROR for a malformed body.

Retrieve all payment policies in your application.

[
  {
    "id": "policy-uuid-here",
    "userId": "user-uuid-here",
    "ownerId": "user-uuid-here",
    "name": "policy_premium_video",
    "amountMsat": "1000",
    "stepValue": 5,
    "currency": "SATS",
    "stepUnitId": "step-unit-uuid-here",
    "createdAt": "2024-01-01T12:00:00Z",
    "stepUnit": {
      "id": "step-unit-uuid-here",
      "name": "SECONDS",
      "unitTypeId": "unit-type-uuid-here",
      "unitType": {
        "id": "unit-type-uuid-here",
        "name": "TIME"
      }
    }
  },
  {
    "id": "policy-uuid-2-here",
    "userId": "user-uuid-2-here",
    "ownerId": "user-uuid-here",
    "name": "policy_audio_stream",
    "amountMsat": "2000",
    "stepValue": 10,
    "currency": "SATS",
    "stepUnitId": "step-unit-uuid-here",
    "createdAt": "2024-01-01T13:00:00Z",
    "stepUnit": {
      "id": "step-unit-uuid-here",
      "name": "SECONDS",
      "unitTypeId": "unit-type-uuid-here",
      "unitType": {
        "id": "unit-type-uuid-here",
        "name": "TIME"
      }
    }
  }
]

Get a specific payment policy by its ID, with the external IDs of its beneficiary and its owner.

Path Parameters

id: Payment policy UUID

{
  "id": "policy-uuid-here",
  "userId": "user-uuid-here",
  "ownerId": "owner-uuid-here",
  "name": "policy_premium_video",
  "amountMsat": "1000",
  "stepValue": 5,
  "currency": "SATS",
  "stepUnitId": "step-unit-uuid-here",
  "createdAt": "2024-01-01T12:00:00Z",
  "stepUnit": {
    "id": "step-unit-uuid-here",
    "name": "SECONDS",
    "unitTypeId": "unit-type-uuid-here",
    "unitType": {
      "id": "unit-type-uuid-here",
      "name": "TIME"
    }
  },
  "user": {
    "externalId": "user_123"
  },
  "owner": {
    "externalId": "user_456"
  }
}

A policy that does not exist in your application answers 200 with the body null. An id that is not a UUID answers 400 VALIDATION_ERROR.

Every payment policy for which the user is the beneficiary — the one who is paid. _count.resources is the number of resources the policy is attached to.

Path Parameters

id: User external ID (e.g., "user_123")

[
  {
    "id": "policy-uuid-here",
    "userId": "user-uuid-here",
    "ownerId": "owner-uuid-here",
    "name": "policy_premium_video",
    "amountMsat": "1000",
    "stepValue": 5,
    "currency": "SATS",
    "stepUnitId": "step-unit-uuid-here",
    "createdAt": "2024-01-01T12:00:00Z",
    "stepUnit": {
      "id": "step-unit-uuid-here",
      "name": "SECONDS",
      "unitTypeId": "unit-type-uuid-here"
    },
    "_count": {
      "resources": 2
    }
  }
]

Every payment policy the user owns — the ones they manage, whoever their beneficiary is. Same response shape as Get Policies for User. A policy created without externalOwnerId is owned by its beneficiary, so it appears in both lists.

Path Parameters

id: Owner external ID (e.g., "user_456")

[
  {
    "id": "policy-uuid-here",
    "userId": "user-uuid-here",
    "ownerId": "owner-uuid-here",
    "name": "policy_premium_video",
    "amountMsat": "1000",
    "stepValue": 5,
    "currency": "SATS",
    "stepUnitId": "step-unit-uuid-here",
    "createdAt": "2024-01-01T12:00:00Z",
    "stepUnit": {
      "id": "step-unit-uuid-here",
      "name": "SECONDS",
      "unitTypeId": "unit-type-uuid-here"
    },
    "_count": {
      "resources": 2
    }
  }
]

Returns the policy of a resource that has exactly one. A resource without any policy (or unknown) answers 200 with the body null. From two policies on, the route answers 409 RESOURCE_HAS_MULTIPLE_POLICIES with details.policyCount: one policy alone is not the price of the resource.

Path Parameters

id: Resource external ID (e.g., "res-123")

{
  "id": "policy-uuid-here",
  "userId": "user-uuid-here",
  "ownerId": "user-uuid-here",
  "name": "policy_premium_video",
  "amountMsat": "1000",
  "stepValue": 5,
  "currency": "SATS",
  "stepUnitId": "step-unit-uuid-here",
  "createdAt": "2024-01-01T12:00:00Z",
  "stepUnit": {
    "id": "step-unit-uuid-here",
    "name": "SECONDS",
    "unitTypeId": "unit-type-uuid-here"
  }
}

Partial update: a field that is absent is left untouched, and null is refused (400). name and externalOwnerId can always be changed; the price and the rhythm only while the policy is attached to no resource.

Path Parameters

id: Payment policy UUID

Request

{
  "name": "policy_updated_name",
  "amount": 10,
  "stepValue": 1,
  "stepUnitKeyName": "SECONDS",
  "externalOwnerId": "user_456"
}

• Attached policy. Changing amount, stepValue or stepUnitKeyName of a policy attached to at least one resource is refused with 409 PAYMENT_POLICY_ATTACHED; details gives resourceCount and up to 50 resourceIds. Sending the current value is accepted.
• Beneficiary. externalUserId is accepted only when it equals the current beneficiary; any other value is refused with 409 PAYMENT_POLICY_BENEFICIARY_IMMUTABLE (details.current).
• id in the body. Tolerated, because older SDKs send it; it must equal the id of the URL, otherwise 400 VALIDATION_ERROR.
• Other errors. 404 PAYMENT_POLICY_NOT_FOUND when the policy does not exist in your application; 400 STEP_UNIT_NOT_FOUND for an unknown step unit; 404 USER_NOT_FOUND or 400 USER_RESERVED for the new owner.

{
  "id": "policy-uuid-here",
  "userId": "user-uuid-here",
  "ownerId": "owner-uuid-here",
  "name": "policy_updated_name",
  "amountMsat": "10000",
  "stepValue": 1,
  "currency": "SATS",
  "stepUnitId": "step-unit-uuid-here",
  "createdAt": "2024-01-01T12:00:00Z"
}

{
  "code": "PAYMENT_POLICY_ATTACHED",
  "message": "The amount and rhythm of an attached policy cannot change: detach it, update it, then attach it again (or replace the group)",
  "details": {
    "resourceCount": 2,
    "resourceIds": ["res-123", "res-456"]
  }
}

Every resource of your application, with its group of policies and the price of a step, sorted by externalResourceId.

[
  {
    "externalResourceId": "res-456",
    "applicationId": "application-uuid-here",
    "policyId": "policy-d-uuid",
    "policyIds": ["policy-d-uuid"],
    "unlockThresholdMsat": null,
    "policy": {
      "id": "policy-d-uuid",
      "userId": "user-d-uuid",
      "ownerId": "user-d-uuid",
      "name": "res-456 price",
      "amountMsat": "2000",
      "stepValue": 10,
      "currency": "SATS",
      "stepUnitId": "step-unit-uuid-here",
      "createdAt": "2026-10-20T09:00:00.000Z",
      "stepUnit": { "id": "step-unit-uuid-here", "name": "SECONDS", "unitTypeId": "unit-type-uuid-here" }
    },
    "policies": [
      {
        "id": "policy-d-uuid",
        "userId": "user-d-uuid",
        "ownerId": "user-d-uuid",
        "name": "res-456 price",
        "amountMsat": "2000",
        "stepValue": 10,
        "currency": "SATS",
        "stepUnitId": "step-unit-uuid-here",
        "createdAt": "2026-10-20T09:00:00.000Z",
        "stepUnit": { "id": "step-unit-uuid-here", "name": "SECONDS", "unitTypeId": "unit-type-uuid-here" },
        "user": { "externalId": "user_d" },
        "owner": { "externalId": "user_d" },
        "position": 0,
        "attachedAt": "2026-10-20T09:01:00.000Z"
      }
    ],
    "pricing": {
      "pricePerStepMsat": "2000",
      "stepValue": 10,
      "stepUnit": { "id": "step-unit-uuid-here", "name": "SECONDS" },
      "currency": "SATS",
      "policyCount": 1,
      "maxPolicies": 10
    }
  }
]

policy is deprecated: it holds the policy when the resource has exactly one, and is null from two policies on — read policies and pricing. policyId is the first policy of the group. Remains accessible while the application is SUSPENDED (read).

Read several resources at once by their external IDs — same items as List Resources; unknown IDs are simply absent from the answer. Pass payerExternalId to add, in pricing, the price that payer would pay: "0" when they are one of the beneficiaries. A read despite the verb: it remains accessible while the application is SUSPENDED.

Request

{
  "resourceIds": ["res-123", "res-456"],
  "payerExternalId": "user_9"
}

[
  {
    "externalResourceId": "res-123",
    "applicationId": "application-uuid-here",
    "policyId": "policy-a-uuid",
    "policyIds": ["policy-a-uuid", "policy-b-uuid", "policy-c-uuid"],
    "unlockThresholdMsat": "500000",
    "policy": null,
    "policies": [
      { "id": "policy-a-uuid", "amountMsat": "5000", "user": { "externalId": "user_a" }, "position": 0, "...": "same fields as in List Resources" },
      { "id": "policy-b-uuid", "amountMsat": "2000", "user": { "externalId": "user_b" }, "position": 1, "...": "same fields as in List Resources" },
      { "id": "policy-c-uuid", "amountMsat": "1000", "user": { "externalId": "user_c" }, "position": 2, "...": "same fields as in List Resources" }
    ],
    "pricing": {
      "pricePerStepMsat": "8000",
      "stepValue": 30,
      "stepUnit": { "id": "step-unit-uuid-here", "name": "SECONDS" },
      "currency": "SATS",
      "policyCount": 3,
      "maxPolicies": 10,
      "payerExternalId": "user_9",
      "payerIsBeneficiary": false,
      "payerPricePerStepMsat": "8000"
    }
  },
  {
    "externalResourceId": "res-456",
    "...": "one policy: policy is filled, see List Resources",
    "pricing": {
      "pricePerStepMsat": "2000",
      "stepValue": 10,
      "stepUnit": { "id": "step-unit-uuid-here", "name": "SECONDS" },
      "currency": "SATS",
      "policyCount": 1,
      "maxPolicies": 10,
      "payerExternalId": "user_9",
      "payerIsBeneficiary": false,
      "payerPricePerStepMsat": "2000"
    }
  }
]

Create a resource with its group of payment policies: policyId for a single policy, or policyIds — 1 to 10 distinct policy UUIDs, in split order — for several. Send exactly one of the two. The whole group is checked against the rules of a group before anything is written; the first policy becomes policyId.

unlockThresholdMsat is optional: a millisatoshi amount as a string — positive integer, 18 digits maximum (e.g. "500000" = 500 sats). When set, the resource unlocks automatically once a user has spent that amount on it. The field is returned in the response as a string, or null when no threshold is set.

Request

{
  "externalResourceId": "res-123",
  "policyIds": ["policy-a-uuid", "policy-b-uuid", "policy-c-uuid"],
  "unlockThresholdMsat": "500000"
}

With a single policy, the historical form still works:

{
  "externalResourceId": "res-456",
  "policyId": "policy-d-uuid"
}

{
  "externalResourceId": "res-123",
  "applicationId": "application-uuid-here",
  "policyId": "policy-a-uuid",
  "policyIds": ["policy-a-uuid", "policy-b-uuid", "policy-c-uuid"],
  "unlockThresholdMsat": "500000"
}

400 RESOURCE_ALREADY_EXIST when the resource already exists; 404 PAYMENT_POLICY_NOT_FOUND (details.policyId) for a policy that does not exist in your application; 400 USER_RESERVED or a 409 for a group rule (RESOURCE_POLICY_RHYTHM_MISMATCH, RESOURCE_BENEFICIARY_ALREADY_PRESENT, RESOURCE_POLICY_LIMIT_REACHED, POLICY_BENEFICIARY_WALLET_MISSING); 400 VALIDATION_ERROR when both or neither of policyId and policyIds are sent, or for an empty, duplicated or oversized list.

Partial update of a resource: send policyIds or policyId, and/or unlockThresholdMsat. A field that is absent is left untouched.

• policyIds replaces the whole group, atomically: the rules of a group apply to the new set, and when they refuse it the previous group stays intact.
• policyId replaces the policy of a resource that has at most one. From two policies on it is refused with 409 RESOURCE_HAS_MULTIPLE_POLICIES (details.policyCount), so that an older client never overwrites a group.
• Sending both policyId and policyIds is refused (400 VALIDATION_ERROR). An empty body answers 404 PAYMENT_POLICY_NOT_FOUND.
• When the resource does not exist, a request carrying policyId creates it (behavior kept for compatibility). policyIds never creates: it answers 404 RESOURCE_NOT_FOUND and nothing is written, so a group replacement that arrives after the resource was deleted never brings it back. To create a resource with a group, use POST /resources. With unlockThresholdMsat alone, the answer is also 404 RESOURCE_NOT_FOUND.

Path Parameters

id: Resource external ID (e.g., "res-123")

Request

{
  "policyIds": ["policy-a-uuid", "policy-e-uuid", "policy-c-uuid"],
  "unlockThresholdMsat": "500000"
}

Sending "unlockThresholdMsat": null removes the threshold — the resource stops being unlockable, but rights already acquired are kept.

{
  "externalResourceId": "res-123",
  "applicationId": "application-uuid-here",
  "policyId": "policy-a-uuid",
  "policyIds": ["policy-a-uuid", "policy-e-uuid", "policy-c-uuid"],
  "unlockThresholdMsat": "500000"
}

The group of a resource: its policies in split order — each with its beneficiary, owner and position — and the price of a step in pricing.

Path Parameters

id: Resource external ID (e.g., "res-123")

Query Parameters

{
  "externalResourceId": "res-123",
  "applicationId": "application-uuid-here",
  "policyId": "policy-a-uuid",
  "policyIds": ["policy-a-uuid", "policy-b-uuid", "policy-c-uuid"],
  "unlockThresholdMsat": "500000",
  "pricing": {
    "pricePerStepMsat": "8000",
    "stepValue": 30,
    "stepUnit": { "id": "step-unit-uuid-here", "name": "SECONDS" },
    "currency": "SATS",
    "policyCount": 3,
    "maxPolicies": 10,
    "payerExternalId": "user_b",
    "payerIsBeneficiary": true,
    "payerPricePerStepMsat": "0"
  },
  "policies": [
    {
      "id": "policy-a-uuid",
      "userId": "user-a-uuid",
      "ownerId": "user-a-uuid",
      "name": "res-123 main share",
      "amountMsat": "5000",
      "stepValue": 30,
      "currency": "SATS",
      "stepUnitId": "step-unit-uuid-here",
      "createdAt": "2026-10-20T10:00:00.000Z",
      "stepUnit": { "id": "step-unit-uuid-here", "name": "SECONDS", "unitTypeId": "unit-type-uuid-here" },
      "user": { "externalId": "user_a" },
      "owner": { "externalId": "user_a" },
      "position": 0,
      "attachedAt": "2026-10-20T10:05:00.000Z"
    },
    {
      "id": "policy-b-uuid",
      "userId": "user-b-uuid",
      "ownerId": "user-a-uuid",
      "name": "res-123 second share",
      "amountMsat": "2000",
      "stepValue": 30,
      "currency": "SATS",
      "stepUnitId": "step-unit-uuid-here",
      "createdAt": "2026-10-20T10:01:00.000Z",
      "stepUnit": { "id": "step-unit-uuid-here", "name": "SECONDS", "unitTypeId": "unit-type-uuid-here" },
      "user": { "externalId": "user_b" },
      "owner": { "externalId": "user_a" },
      "position": 1,
      "attachedAt": "2026-10-20T10:05:00.000Z"
    },
    {
      "id": "policy-c-uuid",
      "userId": "user-c-uuid",
      "ownerId": "user-a-uuid",
      "name": "res-123 third share",
      "amountMsat": "1000",
      "stepValue": 30,
      "currency": "SATS",
      "stepUnitId": "step-unit-uuid-here",
      "createdAt": "2026-10-20T10:02:00.000Z",
      "stepUnit": { "id": "step-unit-uuid-here", "name": "SECONDS", "unitTypeId": "unit-type-uuid-here" },
      "user": { "externalId": "user_c" },
      "owner": { "externalId": "user_a" },
      "position": 2,
      "attachedAt": "2026-10-20T10:05:00.000Z"
    }
  ]
}

404 RESOURCE_NOT_FOUND when the resource does not exist in your application. Remains accessible while the application is SUSPENDED (read). Edge case: a resource named unlocks cannot be read by this route, which GET /resources/unlocks/{payerExternalId} shadows — read it with POST /resources/policies.

Add a policy to the group of an existing resource. The call is idempotent: attaching a policy that is already in the group changes nothing and answers 200. The new policy comes last in the order. No body; the response is the group after the change, in the same shape as Get Resource Policies (without the payer* fields). Sessions already open keep their split.

Path Parameters

id: Resource external ID (e.g., "res-123")
policyId: Payment policy UUID

404 RESOURCE_NOT_FOUND — a resource is never created by this route; 404 PAYMENT_POLICY_NOT_FOUND; 400 USER_RESERVED; 409 POLICY_BENEFICIARY_WALLET_MISSING; 409 RESOURCE_POLICY_LIMIT_REACHED (details.max, details.current); 409 RESOURCE_POLICY_RHYTHM_MISMATCH (details.expected, details.got, details.policyId); 409 RESOURCE_BENEFICIARY_ALREADY_PRESENT (details.userExternalId, details.policyId); 400 VALIDATION_ERROR when policyId is not a UUID.

{
  "code": "RESOURCE_POLICY_RHYTHM_MISMATCH",
  "message": "Every policy of a resource must share the same step and currency",
  "details": {
    "expected": { "stepValue": 30, "stepUnit": "SECONDS", "currency": "SATS" },
    "got": { "stepValue": 60, "stepUnit": "SECONDS", "currency": "SATS" },
    "policyId": "policy-f-uuid"
  }
}

Remove a policy from the group of a resource; the policy itself is kept. Detaching the first policy promotes the next one, so the policyId of the resource changes. The response is the group after the change, in the same shape as Get Resource Policies. Sessions already open keep their split.

Path Parameters

id: Resource external ID (e.g., "res-123")
policyId: Payment policy UUID

404 RESOURCE_NOT_FOUND; 404 RESOURCE_POLICY_NOT_ATTACHED (details.policyId) when the policy is not in the group; 409 RESOURCE_LAST_POLICY for the last policy of the group — delete the resource, or replace its group with PATCH /resources/{id}.

Read whether a user has unlocked a resource, and their progress towards the threshold. If the cumulative spend has already crossed the threshold without the right being materialized (edge case), the read materializes it in passing — best-effort, the response does not depend on it.

Path Parameters

externalResourceId: Resource external ID (e.g., "res-123")
payerExternalId: Paying user external ID (e.g., "user-42")

{
  "externalResourceId": "res-123",
  "payerExternalId": "user-42",
  "unlockable": true,
  "unlockThresholdMsat": "500000",
  "spentMsat": "512000",
  "unlocked": true,
  "unlockedAt": "2026-08-16T12:00:00.000Z"
}

unlocked can be true before unlockedAt exists — the right has not been materialized yet: treat unlocked as the truth. Requires the x-api-key header and is scoped to your application, like the other resource endpoints; it remains accessible while the application is SUSPENDED (read).

Returns 404 RESOURCE_NOT_FOUND when the resource does not exist in your application.

Every resource a user has unlocked, sorted by unlockedAt descending.

Path Parameters

payerExternalId: Paying user external ID (e.g., "user-42")

[
  {
    "externalResourceId": "res-123",
    "payerExternalId": "user-42",
    "thresholdMsat": "500000",
    "spentMsat": "512000",
    "unlockedAt": "2026-08-16T12:00:00.000Z"
  }
]

thresholdMsat and spentMsat are the values recorded at the moment of the unlock. Requires the x-api-key header and is scoped to your application; it remains accessible while the application is SUSPENDED (read).

Current step units available for the TIME unit type:

Retrieve all available unit types with their associated step units.

[
  {
    "id": "unit-type-uuid-here",
    "name": "TIME",
    "units": [
      {
        "id": "step-unit-uuid-1-here",
        "name": "SECONDS"
      },
      {
        "id": "step-unit-uuid-2-here", 
        "name": "MINUTES"
      },
      {
        "id": "step-unit-uuid-3-here",
        "name": "HOURS"
      }
    ]
  }
]

Get all step units for a specific unit type.

Path Parameters

name: Unit type name (e.g., "TIME")

[
  {
    "id": "step-unit-uuid-1-here",
    "name": "SECONDS"
  },
  {
    "id": "step-unit-uuid-2-here",
    "name": "MINUTES"
  },
  {
    "id": "step-unit-uuid-3-here",
    "name": "HOURS"
  }
]

Fields exposed on every debit event. All monetary amounts are millisatoshi strings.

Status lifecycle

1. On the first settled step, one row per policy of the session is created as PENDING in the same transaction as the wallet-to-wallet transfers. A PENDING row therefore means the msat have already moved.
2. On each following step, amountMsat, feesMsat, lostFundsMsat and unitsCharged are incremented on those same rows (and updatedAt advances). Every row of a session moves together: a step pays every share, or none.
3. On session close, the rows flip to SUCCESS with completedAt set. This transition is not reversible.

Rare case. A step settled just after the close can briefly recreate a PENDING row for a policy that already has its SUCCESS row. The finalization of the session then merges it into that SUCCESS row — whose id is kept — and deletes the PENDING row, which therefore no longer appears in the listing. If you had imported it: for the same sessionId and policyId, a local PENDING row whose updatedAt is earlier than a SUCCESS row received afterwards has been merged — remove it.

List every debit event that changed since your last import, with a stable cursor. Scoped to the application owning the API key.

Query Parameters

Guarantees

• Stable ordering (updatedAt ASC, id ASC) with a composite cursor on both fields. A timestamp-only cursor would drop rows written in the same millisecond.
• updatedSince is inclusive. Re-importing an event you already have is harmless (upsert is idempotent); missing one is not recoverable.
• Scoped to your application. An application only ever sees its own events.
• All statuses are returned, PENDING included.
• nextCursor is null on the last page (hasMore: false).

{
  "items": [
    {
      "id": "3f9a1c02-7b4e-4c11-9d33-2a5f8e6b0d71",
      "sessionId": "9c2e6f18-13ab-4d75-8f21-6b0c7d9a4e35",
      "amountMsat": "40000",
      "feesMsat": "4000",
      "status": "SUCCESS",
      "createdAt": "2026-08-09T10:00:20.004Z",
      "updatedAt": "2026-08-09T10:00:40.012Z",
      "completedAt": "2026-08-09T10:00:40.012Z",
      "startedAt": "2026-08-09T09:59:58.881Z",
      "payerExternalId": "user_123",
      "applicationId": "b71d4c8e-5a02-4f96-8c17-3e9d0b2a6f54",
      "unitsCharged": 20,
      "resourceId": "res-123",
      "policyId": "e2c7a940-8d61-4b3f-95ea-1c8f7d206b43",
      "currency": "SATS",
      "shareIndex": 0,
      "lostFundsMsat": "0"
    }
  ],
  "nextCursor": "eyJ1cGRhdGVkQXQiOiIyMDI2LTA4LTA5VDEwOjAwOjQwLjAxMloiLCJpZCI6IjNmOWExYzAyIn0",
  "hasMore": true
}

Import loop

// SDK 2.0 — `iterate` follows `nextCursor` until `hasMore === false`
let high = lastSyncedAt

for await (const event of client.debitEvent.iterate({
  updatedSince: lastSyncedAt,
  limit: 500,
})) {
  const netMsat = BigInt(event.amountMsat) - BigInt(event.feesMsat)
  await db.debitEvent.upsert({ where: { id: event.id }, /* ... */ })
  if (event.updatedAt > high) high = event.updatedAt
}

// Persist `high` only at the end of a full cycle.
// A crash mid-cycle replays the window, which the upsert makes harmless.

{
  "code": "INVALID_CURSOR",
  "message": "Invalid pagination cursor. Restart the page from `updatedSince`.",
  "details": null
}

A bad cursor always fails loudly — it never silently restarts from the beginning of the collection.

Retrieve all debit events for a specific user with optional date range filtering.

Path Parameters

Query Parameters

[
  {
    "id": "debit-event-uuid-1",
    "sessionId": "session-uuid-1",
    "amountMsat": "100000",
    "feesMsat": "10000",
    "status": "SUCCESS",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-01-15T10:00:01.000Z",
    "completedAt": "2026-01-15T10:00:01.000Z",
    "startedAt": "2026-01-15T09:59:55.000Z",
    "payerExternalId": "user_123",
    "applicationId": "application-uuid",
    "unitsCharged": 20,
    "policyId": "policy-uuid",
    "resourceId": "resource-id-1",
    "currency": "SATS",
    "shareIndex": 0,
    "lostFundsMsat": "0",
    "policy": {
      "id": "policy-uuid",
      "name": "Premium Video Stream",
      "amountMsat": "1000",
      "stepValue": 5,
      "currency": "SATS",
      "user": {
        "id": "user-uuid",
        "externalId": "user_123"
      },
      "stepUnit": {
        "id": "step-unit-uuid",
        "name": "SECONDS",
        "unitTypeId": "unit-type-uuid"
      }
    }
  },
  {
    "id": "debit-event-uuid-2",
    "sessionId": "session-uuid-2",
    "amountMsat": "50000",
    "feesMsat": "5000",
    "status": "SUCCESS",
    "createdAt": "2026-01-20T14:30:00.000Z",
    "updatedAt": "2026-01-20T14:30:01.000Z",
    "completedAt": "2026-01-20T14:30:01.000Z",
    "startedAt": "2026-01-20T14:29:50.000Z",
    "payerExternalId": "user_123",
    "applicationId": "application-uuid",
    "unitsCharged": 5,
    "policyId": "policy-uuid-2",
    "resourceId": "resource-id-2",
    "currency": "SATS",
    "shareIndex": 0,
    "lostFundsMsat": "0",
    "policy": {
      "id": "policy-uuid-2",
      "name": "Standard Audio Stream",
      "amountMsat": "1000",
      "stepValue": 10,
      "currency": "SATS",
      "user": {
        "id": "user-uuid",
        "externalId": "user_123"
      },
      "stepUnit": {
        "id": "step-unit-uuid",
        "name": "SECONDS",
        "unitTypeId": "unit-type-uuid"
      }
    }
  }
]

Retrieve all debit events for a specific resource with optional date range filtering.

Path Parameters

Query Parameters

[
  {
    "id": "debit-event-uuid-3",
    "sessionId": "session-uuid-3",
    "amountMsat": "200000",
    "feesMsat": "20000",
    "status": "SUCCESS",
    "createdAt": "2026-01-10T09:15:00.000Z",
    "updatedAt": "2026-01-10T09:15:01.000Z",
    "completedAt": "2026-01-10T09:15:01.000Z",
    "startedAt": "2026-01-10T09:14:59.000Z",
    "payerExternalId": "user_777",
    "applicationId": "application-uuid",
    "unitsCharged": 100,
    "policyId": "policy-uuid",
    "resourceId": "video_stream_001",
    "currency": "SATS",
    "shareIndex": 0,
    "lostFundsMsat": "0",
    "policy": {
      "id": "policy-uuid",
      "name": "Premium Video Stream",
      "amountMsat": "2000",
      "stepValue": 1,
      "currency": "SATS",
      "user": {
        "id": "user-uuid",
        "externalId": "content_creator_456"
      },
      "stepUnit": {
        "id": "step-unit-uuid",
        "name": "SECONDS",
        "unitTypeId": "unit-type-uuid"
      }
    }
  },
  {
    "id": "debit-event-uuid-4",
    "sessionId": "session-uuid-4",
    "amountMsat": "150000",
    "feesMsat": "15000",
    "status": "SUCCESS",
    "createdAt": "2026-01-12T11:20:00.000Z",
    "updatedAt": "2026-01-12T11:20:02.000Z",
    "completedAt": "2026-01-12T11:20:02.000Z",
    "startedAt": "2026-01-12T11:19:58.000Z",
    "payerExternalId": "user_888",
    "applicationId": "application-uuid",
    "unitsCharged": 75,
    "policyId": "policy-uuid",
    "resourceId": "video_stream_001",
    "currency": "SATS",
    "shareIndex": 0,
    "lostFundsMsat": "0",
    "policy": {
      "id": "policy-uuid",
      "name": "Premium Video Stream",
      "amountMsat": "2000",
      "stepValue": 1,
      "currency": "SATS",
      "user": {
        "id": "user-uuid",
        "externalId": "content_creator_456"
      },
      "stepUnit": {
        "id": "step-unit-uuid",
        "name": "SECONDS",
        "unitTypeId": "unit-type-uuid"
      }
    }
  }
]

What one session cost, and who received it: one line per policy, with the share of one step, the amounts paid, the commission and the lost funds. PENDING and SUCCESS events are both counted. Scoped to your application.

Path Parameters

{
  "sessionId": "9c2e6f18-13ab-4d75-8f21-6b0c7d9a4e35",
  "status": "CLOSED",
  "resourceId": "res-123",
  "payerExternalId": "user_9",
  "startedAt": "2026-10-20T10:10:00.000Z",
  "currency": "SATS",
  "selfListening": false,
  "pricePerStepMsat": "8000",
  "totalMsat": "16000",
  "totalFeesMsat": "1600",
  "totalNetMsat": "14400",
  "totalLostFundsMsat": "0",
  "unitsCharged": 2,
  "lines": [
    {
      "shareIndex": 0,
      "policyId": "policy-a-uuid",
      "beneficiaryExternalId": "user_a",
      "amountPerStepMsat": "5000",
      "amountMsat": "10000",
      "feesMsat": "1000",
      "netMsat": "9000",
      "lostFundsMsat": "0",
      "unitsCharged": 2,
      "status": "SUCCESS",
      "completedAt": "2026-10-20T10:11:00.000Z"
    },
    {
      "shareIndex": 1,
      "policyId": "policy-b-uuid",
      "beneficiaryExternalId": "user_b",
      "amountPerStepMsat": "2000",
      "amountMsat": "4000",
      "feesMsat": "400",
      "netMsat": "3600",
      "lostFundsMsat": "0",
      "unitsCharged": 2,
      "status": "SUCCESS",
      "completedAt": "2026-10-20T10:11:00.000Z"
    },
    {
      "shareIndex": 2,
      "policyId": "policy-c-uuid",
      "beneficiaryExternalId": "user_c",
      "amountPerStepMsat": "1000",
      "amountMsat": "2000",
      "feesMsat": "200",
      "netMsat": "1800",
      "lostFundsMsat": "0",
      "unitsCharged": 2,
      "status": "SUCCESS",
      "completedAt": "2026-10-20T10:11:00.000Z"
    }
  ]
}

404 DEBIT_SESSION_NOT_FOUND when your application has nothing for this session — the session of another application answers the same. An identifier longer than 100 characters is refused (414). Remains accessible while the application is SUSPENDED (read).

Totals, number of billed sessions and unique payers over a period. Scoped to the application owning the API key.

Query Parameters

Both bounds apply to createdAt — the only timestamp that is never null, including on historical rows.

{
  "totalMsat": "120000",
  "totalFeesMsat": "12000",
  "eventCount": 7,
  "debitEventCount": 11,
  "uniquePayers": 3
}

Overview

WebSocket streaming allows real-time payment streaming based on time. Your application connects to PayEngine's WebSocket server to start, pause, resume, and stop payment streams between users according to your payment policies.

Setup Process

PATCH /applications/public-key
Content-Type: application/json

{
  "publicKey": "-----BEGIN PUBLIC KEY-----\n..."
}

PATCH /applications/webhook-url
Content-Type: application/json

{
  "webhookUrl": "https://your-app.com/webhooks/payengine"
}

// Example JWT generation
const jwt = require('jsonwebtoken');

const payload = {
  sub: 'your-app-id',              // Application ID
  resourceId: 'res-123',           // Resource the session pays for
  userExternalId: 'user_payer',    // Payer user external ID
  iat: Math.floor(Date.now() / 1000),
  exp: Math.floor(Date.now() / 1000) + (5 * 60) // 5 minutes
};

const token = jwt.sign(payload, privateKey, {
  algorithm: 'RS256',
  keyid: 'your-key-id'  // Optional key identifier
});

WebSocket Connection

const WebSocket = require('ws');

const ws = new WebSocket('wss://payengine.metronomiq.io/stream', {
  headers: {
    'authorization': `Bearer ${jwtToken}`
  }
});

ws.on('open', () => {
  console.log('🟢 WebSocket connection established');
});

ws.on('message', data => {
  const msg = JSON.parse(data);
  console.log('📨 Received:', msg);
});

Current state of the production API, read from the two endpoints below. Refreshed every minute while this page is open.

• API /api/health — Checking…

• Lightning payments /api/health/lightning — Checking…

Last checked: —

Three dependencies are probed on every call. Two are live round-trips; the third reads a heartbeat, so a hung Lightning node turns the component down on its own after about ninety seconds.

{
  "status": "ok",
  "info": {
    "database": { "status": "up" },
    "redis": { "status": "up" },
    "lnd": { "status": "up", "reconnecting": false, "heartbeatAgeMs": 1000 }
  },
  "error": {},
  "details": { "...": "same as info" }
}

{
  "status": "error",
  "info": { "redis": { "status": "up" } },
  "error": {
    "database": { "status": "down", "message": "unreachable" },
    "lnd": {
      "status": "down", "reconnecting": true, "hasConnection": false,
      "heartbeatAgeMs": 120000, "heartbeatMaxAgeMs": 90000
    }
  },
  "details": { "...": "every component, up or down" }
}

This is the one response that does not follow the standard error envelope described below — it keeps its own shape so that monitoring tools can read it directly. Failure messages stay deliberately vague: no connection string, no node address.

Stricter than /api/health: it tells whether the Lightning node can process deposits and withdrawals right now. A node can keep answering simple queries while its payment database is stuck or its view of the blockchain is frozen — this endpoint catches both. While it reports down, PayEngine refuses new deposits and withdrawals with 503 LIGHTNING_UNAVAILABLE instead of starting them.

{
  "status": "ok",
  "info": {
    "lightning": {
      "status": "up",
      "blockHeight": 915000,
      "operationalSince": "2026-09-17T09:00:00.000Z"
    }
  },
  "error": {},
  "details": { "...": "same as info" }
}

{
  "status": "error",
  "info": {},
  "error": {
    "lightning": {
      "status": "down",
      "degradedReasons": ["node-database-unresponsive"],
      "blockHeight": 915000,
      "heartbeatAgeMs": 12000
    }
  },
  "details": { "...": "same as error" }
}

Poll it (once a minute is plenty) to warn your users before they try to deposit or withdraw. /api/health can stay green while this one is down: the service is up, but payments are paused.

Error Format

{
  "code": "USER_NOT_FOUND",
  "message": "User not found",
  "details": null
}

The HTTP status carries the category; code is stable and is what your code should branch on — never the message, which may change. details is null, a short diagnostic string, or an object with structured data — for example { "max": 10, "current": 10 } for RESOURCE_POLICY_LIMIT_REACHED.

Every answer of a money route tells you where the funds are. The last column is what your integration should do.