Broadcast Transactions

Submit a signed transaction to the blockchain through StarkNode’s payment infrastructure. Never broadcast directly from the user’s wallet.

POST /payment/execute/on-chain

cURL

curl --request POST \
  --url https://api.starknode.io/payment/execute/on-chain \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "executor_id": "api_transaction",
    "payment_id": "cmoejr9eh000401nyffxgmxtj",
    "signed_transaction": "0x02f8b282a4ec..."
  }'

200 - Payment confirmed (broadcast completed)

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

x-api-key · string · required

Your StarkNode API key. You can find it in your dashboard.

You must always use this endpoint for all on-chain operations. 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 it here. This ensures all required steps for payment processing and order confirmation are properly executed.

executor_id · string · required

Transaction executor type. Use api_transaction when the request comes via API.

payment_id · string · required

Unique payment identifier generated in the Create Transaction step.

signed_transaction · string · required

Signed transaction hex string generated by the user’s wallet after signing the crypto_tx received from the create transaction endpoint.

cURL

curl --request POST \
  --url https://api.starknode.io/payment/execute/on-chain \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "executor_id": "api_transaction",
    "payment_id": "cmoejr9eh000401nyffxgmxtj",
    "signed_transaction": "0x02f8b282a4ec..."
  }'

200 - Payment confirmed (broadcast completed)

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

Response

statusCode · number · required

HTTP status code. Returns 200 on success.

success · boolean · required

Whether the request succeeded.

status · enum<string> · required

Broadcast result status. Available options: payment_confirmed, payment_received

• payment_confirmed — broadcast accepted and transaction receipt confirmed on-chain. Order status updated to success.
• payment_received — transaction confirmed on source chain. Worker (FinalizerTransferWorker) takes over to monitor the bridge via LiFi. Order status updated to received.

message · string · required

Human-readable response message.

data · object · required

Broadcast result data.

Show data

id · string · required

Internal order ID in StarkNode.

tid_hash · string

Confirmed transaction hash on the blockchain. Present on payment_confirmed.

tx_hash · string

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

---

Errors

Before broadcast

These occur during payload or order validation, before any transaction 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

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

Once broadcast is submitted, the order moves through the following states:

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)

Use the Check Payment Info endpoint to poll the order status after broadcasting and confirm when it reaches success.