> ## Documentation Index
> Fetch the complete documentation index at: https://docs.starkfi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Broadcast transactions

> Required endpoint for StarkPay on-chain payments. Sign the transaction in your app, then submit exclusively through this endpoint.

<Warning>
  This endpoint is **required for StarkPay** on-chain payments. Yield Aggregator operations may be broadcast on your own RPC — see [Broadcast yield operations](/broadcast-your-operations) (optional).
</Warning>

```shellscript theme={null}
POST /payment/execute/on-chain
```

<Steps>
  <Step title="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                |
  </Step>
</Steps>

***

## Expected Response

<Tabs>
  <Tab title="Payment confirmed (on-chain broadcast completed)">
    The broadcast was accepted and the transaction receipt confirmed it. The order status is updated to `success`.

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

    <ResponseField name="data.id" type="string">
      Internal order ID in StarkFi
    </ResponseField>

    <ResponseField name="data.tid_hash" type="string">
      Confirmed transaction hash on the blockchain
    </ResponseField>
  </Tab>

  <Tab title="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`.

    ```json theme={null}
    {
      "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"
      }
    }
    ```

    <ResponseField name="data.id" type="string">
      Internal order ID in StarkFi
    </ResponseField>

    <ResponseField name="data.tx_hash" type="string">
      Transaction hash on the source chain. The final destination is processed by the worker
    </ResponseField>
  </Tab>
</Tabs>

## Errors

<AccordionGroup>
  <Accordion title="Errors before broadcast" icon="shield-halved">
    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                   |
  </Accordion>

  <Accordion title="Errors during broadcast" icon="triangle-exclamation">
    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 |
  </Accordion>
</AccordionGroup>

## Order Status Lifecycle

```text theme={null}
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)
```