Broadcast transactions

This endpoint is intended for all on-chain operations processed through our payment infrastructure. You must always use this endpoint and never send transactions via your own broadcast or directly through the user’s wallet (e.g., using sendTransaction). The user should only sign the transaction. After signing, your backend must forward the transaction to the API’s broadcast endpoint. This ensures that all required steps for payment processing and order confirmation are properly executed.

POST /payment/execute/on-chain

1. Broadcast transaction

   Broadcasting a transaction

   Parameter	Type	Required	Description
   executor_id	string	✅	Transaction executor type. Use api_transaction when request comes via API
   payment_id	string	✅	Unique payment identifier generated in the previous step
   signed_transaction	string	✅	Signed transaction hex string generated by the user’s wallet

---

Expected Response

Payment confirmed (on-chain broadcast completed)

The broadcast was accepted and the transaction receipt confirmed it. The order status is updated to success.

{
  "statusCode": 200,
  "success": true,
  "status": "payment_confirmed",
  "message": "Payment confirmed",
  "data": {
    "id": "cmoejr9eh000401nyffxgmxtj",
    "tid_hash": "0xabc123...def456"
  }
}

data.id · string

Internal order ID in StarkNode

data.tid_hash · string

Confirmed transaction hash on the blockchain

Payment received (awaiting bridge processing)

The incoming transaction was confirmed on the source chain. The worker (FinalizerTransferWorker) takes over and monitors the bridge via LiFi. The order status is updated to received.

{
  "statusCode": 200,
  "success": true,
  "status": "payment_received",
  "message": "Payment received...waiting for worker to send transaction to blockchain.",
  "data": {
    "id": "cmoejr9eh000401nyffxgmxtj",
    "tx_hash": "0xabc123...def456"
  }
}

data.id · string

Internal order ID in StarkNode

data.tx_hash · string

Transaction hash on the source chain. The final destination is processed by the worker

Errors

Errors before broadcast

These occur during payload or order validation, before any broadcast is sent to the network.

HTTP	status	When it occurs
400	invalid_parameters	Invalid payload (schema validation failed)
400	invalid_chain	Order’s chain is not enabled or not supported
404	payment_not_found	payment_id does not exist
409	invalid_payment_status	Order is not in registered or retry status
409	missing_unsigned_transaction	Unsigned tx was not generated before execute
400	invalid_signed_transaction	Invalid signature or mismatch with the unsigned tx
400	stale_transaction_nonce	Transaction nonce is out of sync

Errors during broadcast

These occur after validation, during or after the broadcast to the network.

HTTP	status	When it occurs
500	payment_failed	Receipt received but transaction was reverted on-chain
500	finalizer_payment_order_on_chain_failed	Unexpected exception inside the finalizer
500	blockchain_transaction_failed	Exception caught by the controller before reaching the finalizer

Order Status Lifecycle

registered / retry
  → processing          (execute started)
  → processing          (signed_tx saved)
  → success             (FinalizerTransferOnChain: broadcast confirmed)
  → received            (FinalizerBridgeSwapOnChain: waiting for worker)
  → success             (worker completes the bridge)
  → error               (any failure along the way)