Get Started
Accept Per-call Payments
The Developer API takes per-call payments. Your own server can take them too. A facilitator does the payment side for you: it checks each debit authorization and settles it on chain, so your server never sends a payment transaction.
Experimental: the prepaid-debit scheme and the facilitator may change. Per-call payments use the x402 v2 headers with Lightchain AI's own scheme, so standard x402 clients cannot pay them, and standard x402 facilitators cannot settle them.
What the facilitator does, and what it doesn't
A per-call payment settles by submitting a job:JobRegistry.submitJobWithDebitAuthorization checks the payer's signature, submits the job into a session your server owns, and debits the job's fee from the payer's prepaid balance. The facilitator sends that transaction and pays its gas.
Your server still runs the job itself, as for any Lightchain AI job:
- it owns an active session for the model (it is the
payToof every payment), - it encrypts the prompt with that session's key and posts it as an EIP-4844 blob, and
- it reads the worker's answer and returns it to the caller.
One-time setup
-
Pick the address that owns your sessions. It is your
payTo. -
From it, consent to the facilitator once. Settlements for any other
payToare refused on chain.This spends nothing of your own: the facilitator's allowance on your balance stays 0 unless you raise it, so it can only settle what a payer signed, into your sessions. Revoke it withCodeBASHfalse.
Endpoints
The request and response bodies follow the x402 v2 facilitator API.CodeBASH
CodeJSON
/verify and /settle answer 200 whatever the decision. An unreadable body gets 400 with reason invalid_payload. The reasons are the ones in the pay-per-call codes, and a few more:
invalid_transaction_state: the chain refused the settlement for another reason, such as an inactive session.unexpected_verify_error,unexpected_settle_error: the facilitator could not reach the chain.- If the
errorMessageof anunexpected_settle_errornames a transaction, the settlement was sent but its receipt did not arrive within 60 seconds. It may still land, so look the transaction up before you refuse the call.
- If the
/settle of the same authorization is refused as invalid_prepaid_debit_payload_nonce_used, even while the first one is still in flight, so a payment is never settled twice. Requests are rate-limited per client IP; over the limit, the answer is 429.
A server that takes a payment
Your server answers402 with its requirements, verifies the payment the caller retries with, settles it, and then serves. Settling submits the job, so it happens before you answer:
CodeJAVASCRIPT
Related pages
- Payment: the payer's side, the debit authorization and its codes.
- Custody and Trust: what a payer's signature allows.
- Verifying an Answer: how a caller checks the job behind an answer.