Broadcast transactions

This endpoint is required for StarkPay on-chain payments. Yield Aggregator operations may be broadcast on your own RPC — see Broadcast yield operations (optional).

POST /payment/execute/on-chain

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)
Payment received (awaiting bridge processing)

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"
  }
}

string

Internal order ID in StarkFi

string

Confirmed transaction hash on the blockchain

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"
  }
}

string

Internal order ID in StarkFi

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)

Overview

Guides

Expected Response

Errors

Order Status Lifecycle

​Expected Response

​Errors

​Order Status Lifecycle

Expected Response

Errors

Order Status Lifecycle