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

# Place an order

> Place a duty credit scrip sell or buy order on ScripX with a price floor in bps of face and safe retries via the Idempotency-Key header.

Submits a sell or buy order for matching. Requires the `orders:write` scope. Returns `201` with the created order.

Send an `Idempotency-Key` header on every call: re-sending the same key returns the original order, so a network timeout never becomes a duplicate trade.

### Request example

```bash theme={"dark"}
curl -X POST "https://api.scripxhq.com/v1/orders" \
  -H "X-ScripX-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3d2c9a-order-1" \
  -d '{"side": "sell", "scheme": "RODTEP", "amount_paise": 100000000, "min_pct_bps": 9600}'
```

`side`, `scheme` and `amount_paise` are required. Your limit is structural, not advisory: a **sell** carries `min_pct_bps`, the floor it never fills below; a **buy** carries `max_pct_bps`, the ceiling it never fills above.

### Response example

```json theme={"dark"}
{
  "order": {
    "order_id": "ord_01HZX…",
    "side": "sell",
    "scheme": "RODTEP",
    "amount_paise": 100000000,
    "min_pct_bps": 9600,
    "status": "open",
    "created_at": "2026-07-24T11:02:41+05:30"
  }
}
```

### Errors

* `401` / `403` / `429`, the standard [auth errors](/authentication#authentication-errors).
* `422 unprocessable`, invalid side, scheme or amount.

**Terms used here:** [scheme](/annexure/terminology#scheme), [paise](/annexure/terminology#paise), [bps](/annexure/terminology#basis-point), [price floor](/annexure/terminology#price-floor-and-ceiling), [order](/annexure/terminology#order), [position](/annexure/terminology#position), [API key](/annexure/terminology#api-key), [scope](/annexure/terminology#scope), [idempotency key](/annexure/terminology#idempotency-key). Full list in the [terminology annexure](/annexure/terminology).

### Next steps

* [Get the order](/api-reference/trading/orders-get), or [positions](/api-reference/trading/positions) for the whole book.
* [Register a webhook](/api-reference/webhooks/register) for `order.matched`.


## OpenAPI

````yaml POST /v1/orders
openapi: 3.1.0
info:
  title: ScripX Partner API
  version: 1.2.0
  description: >-
    Automate duty-credit-scrip trading: quote, order, positions, market,
    webhooks. Auth: `X-ScripX-Key: scripx_live_…`. Money = integer paise; price
    = bps of face.
  contact:
    name: ScripX API Support
    email: amin@eximfiles.io
    url: https://scripxhq.com
servers:
  - url: https://api.scripxhq.com
    description: >-
      Production and sandbox share one host; a scripx_test_ key selects the
      sandbox.
security:
  - ApiKeyAuth: []
tags:
  - name: Firms
    description: >-
      client-firm lifecycle: register, verify, authorize, credits, update,
      offboard
  - name: Trading
    description: quote, orders, positions, market
  - name: Group
    description: intra-group netting + positions (enterprise/broker)
  - name: Cross
    description: 'broker cross-desk: block deals + intra-group transfers'
  - name: Webhooks
    description: event subscriptions + delivery
  - name: Account
    description: usage + metering
  - name: Keys
    description: self-serve scoped child keys (sub-accounts)
paths:
  /v1/orders:
    post:
      tags:
        - Trading
      summary: Place an order
      parameters:
        - name: Idempotency-Key
          in: header
          schema:
            type: string
          description: Safe-retry key; re-sending returns the original order.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    OrderRequest:
      type: object
      required:
        - side
        - scheme
        - amount_paise
      properties:
        side:
          type: string
          enum:
            - sell
            - buy
        scheme:
          type: string
        amount_paise:
          type: integer
        min_pct_bps:
          type: integer
          description: 'sell only: price floor in bps of face; never fills below'
        max_pct_bps:
          type: integer
          description: 'buy only: price ceiling in bps of face; never fills above'
    Order:
      type: object
      properties:
        order:
          type: object
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          description: stable machine code
          enum:
            - bad_request
            - unauthorized
            - forbidden
            - not_found
            - conflict
            - unprocessable
            - rate_limited
            - internal
        message:
          type: string
        detail:
          type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-ScripX-Key
      description: >-
        Your API key, e.g. `scripx_live_…`. Bound to one firm; tenant isolation
        is enforced.

````