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

# Submit On-chain Order

> Report the on-chain orderId after submitting createOrder on an EVM or Starknet chain, so Rails can track the order and webhook you on status changes.

After your wallet submits `createOrder(...)` with the params from
[Create Order — EVM & Starknet](/api-reference/endpoint-prepare-evm-order), the
Gateway emits an `OrderCreated` event carrying the `orderId`. Report that
`orderId` (and the tx hash) back to Rails with this call.

Rails is non-custodial and does not index EVM/Starknet chains, so this callback
is how it learns the order exists. Once recorded, Rails polls the settlement
aggregator by `(chainId, orderId)` and delivers a [webhook](/webhooks) to your
configured URL on each settlement state change (`settled`, `refunded`,
`expired`).

### Header Parameters

<ParamField header="API-Key" type="string" required>
  Unique API key issued manually through Telegram.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  The `orderRef` (UUID) returned by Prepare EVM Order.
</ParamField>

### Request Body

<ParamField body="orderId" type="string" required>
  The `bytes32` order id (0x-hex) from the Gateway's `OrderCreated` event.
</ParamField>

<ParamField body="txHash" type="string" required>
  The transaction hash of your `createOrder` submission.
</ParamField>

### Response

<ResponseField name="status" type="string">Response state (`success`).</ResponseField>
<ResponseField name="message" type="string">Human-readable message.</ResponseField>

<ResponseField name="data" type="object">
  <ResponseField name="orderRef" type="string">Rails order id.</ResponseField>
  <ResponseField name="gatewayId" type="string">The recorded on-chain order id.</ResponseField>
  <ResponseField name="status" type="string">Lifecycle state — now `pending`.</ResponseField>
</ResponseField>

<Note>
  An order can only be submitted once, and only while in the `initiated` state.
  Re-submitting returns `400`.
</Note>

***

### Example Payloads

<RequestExample>
  ```json Request theme={null}
  {
    "orderId": "0x9a3f1c7e2b4d5f6a8c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
    "txHash": "0xabc123def456..."
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response (200 OK) theme={null}
  {
    "status": "success",
    "message": "Submission recorded — we'll poll status and webhook you on changes",
    "data": {
      "orderRef": "c7326d65-dfff-44c2-8bcc-c0756dfb6c0a",
      "gatewayId": "0x9a3f1c7e2b4d5f6a8c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
      "status": "pending"
    }
  }
  ```
</ResponseExample>