> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create an order
> Submit a quote for execution. Persist the idempotency key before sending the request and track the returned order until it reaches a terminal state. Examples contain captured Sandbox identifiers. Request a fresh quote and use a new idempotency key for a new operation.
```bash cURL
curl --request POST \
--url 'https://api-sandbox.uqpaytech.com/api/v1/stocks/order' \
--header "Content-Type: application/json" \
--header "x-auth-token: Bearer ${SANDBOX_TOKEN}" \
--header "x-idempotency-key: ${UNIQUE_IDEMPOTENCY_KEY}" \
--data '{
"quote_id": "0576b03b-56dd-48b1-ba24-058ce90d0f53",
"client_reference": "stocks-docs-20260921-buy-01"
}'
```
```json 200
{
"transfer_quantity": null,
"order_id": "53fe3d55-85ff-4804-b6f0-a25a32aa082f",
"quote_id": "0576b03b-56dd-48b1-ba24-058ce90d0f53",
"client_reference": "stocks-docs-20260921-buy-01",
"asset_id": "7453f146-b267-11f1-b4f4-0abd773ba497",
"symbol": "AAPLx",
"side": "BUY",
"status": "PENDING",
"network": "Ethereum",
"funding_currency": "USDC",
"quoted_quantity": "0.00297066689243735",
"executed_quantity": null,
"executed_price": null,
"cash_amount": null,
"fees": null,
"total_amount": null,
"transaction_hash": "0x7e7b7f06c0a4adce2ec2bc01b455fd4e014b9f298e7e2598b02c93dffa86a96f",
"failure_code": null,
"failure_message": null,
"created_at": "2026-09-21T01:33:08.629Z",
"updated_at": "2026-09-21T01:33:13.84Z",
"completed_at": null,
"failed_at": null
}
```
## OpenAPI
````yaml /stocks/stocks.yaml post /order
openapi: 3.0.3
info:
title: UQPAY Stocks API
version: 1.0.0
description: >-
Browse assets, request quotes, create orders, and query orders and
positions. Amounts and quantities use decimal strings.
servers:
- url: https://api-sandbox.uqpaytech.com/api/v1/stocks
description: Sandbox
security:
- AuthToken: []
paths:
/order:
post:
tags:
- Stocks
summary: Create an order
description: >-
Submit a quote for execution. Persist the idempotency key before sending
the request and track the returned order until it reaches a terminal
state. Examples contain captured Sandbox identifiers. Request a fresh
quote and use a new idempotency key for a new operation.
operationId: createStocksOrder
parameters:
- name: x-idempotency-key
in: header
required: true
schema:
type: string
format: uuid
pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
description: >-
A unique identifier used to maintain operation idempotency. Use the
same key and request body when retrying an operation, and a new key
for a new operation.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRequest'
examples:
sandbox:
summary: Sandbox request
value:
quote_id: 0576b03b-56dd-48b1-ba24-058ce90d0f53
client_reference: stocks-docs-20260921-buy-01
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
sandbox:
summary: Sandbox response
value:
transfer_quantity: null
order_id: 53fe3d55-85ff-4804-b6f0-a25a32aa082f
quote_id: 0576b03b-56dd-48b1-ba24-058ce90d0f53
client_reference: stocks-docs-20260921-buy-01
asset_id: 7453f146-b267-11f1-b4f4-0abd773ba497
symbol: AAPLx
side: BUY
status: PENDING
network: Ethereum
funding_currency: USDC
quoted_quantity: '0.00297066689243735'
executed_quantity: null
executed_price: null
cash_amount: null
fees: null
total_amount: null
transaction_hash: >-
0x7e7b7f06c0a4adce2ec2bc01b455fd4e014b9f298e7e2598b02c93dffa86a96f
failure_code: null
failure_message: null
created_at: '2026-09-21T01:33:08.629Z'
updated_at: '2026-09-21T01:33:13.84Z'
completed_at: null
failed_at: null
'400':
description: >-
The request failed. Read type, code, and message in the error
response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: >-
The request failed. Read type, code, and message in the error
response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: >-
The request failed. Read type, code, and message in the error
response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: >-
The request failed. Read type, code, and message in the error
response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: >-
The request failed. Read type, code, and message in the error
response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: >-
The request failed. Read type, code, and message in the error
response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'502':
description: >-
The gateway could not complete the request. For a write, reconcile
the result before retrying with the same idempotency key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: >-
The request failed. Read type, code, and message in the error
response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-codeSamples:
- lang: cURL
source: |-
curl --request POST \
--url 'https://api-sandbox.uqpaytech.com/api/v1/stocks/order' \
--header "Content-Type: application/json" \
--header "x-auth-token: Bearer ${SANDBOX_TOKEN}" \
--header "x-idempotency-key: ${UNIQUE_IDEMPOTENCY_KEY}" \
--data '{
"quote_id": "0576b03b-56dd-48b1-ba24-058ce90d0f53",
"client_reference": "stocks-docs-20260921-buy-01"
}'
components:
schemas:
OrderRequest:
type: object
additionalProperties: false
properties:
quote_id:
type: string
format: uuid
description: Quote identifier to submit when creating an order.
example: 0576b03b-56dd-48b1-ba24-058ce90d0f53
client_reference:
type: string
minLength: 1
maxLength: 100
nullable: true
description: >-
Your reference for querying orders. It does not replace the
idempotency key.
example: stocks-docs-20260921-buy-01
required:
- quote_id
Order:
type: object
additionalProperties: false
properties:
order_id:
type: string
format: uuid
description: Order identifier used to retrieve an order.
example: 53fe3d55-85ff-4804-b6f0-a25a32aa082f
quote_id:
type: string
format: uuid
description: >-
Quote used for a trade order. Null for deposit and withdrawal
records.
nullable: true
example: 0576b03b-56dd-48b1-ba24-058ce90d0f53
client_reference:
type: string
nullable: true
description: >-
Your reference for querying orders. It does not replace the
idempotency key.
example: stocks-docs-20260921-buy-01
asset_id:
type: string
format: uuid
description: >-
Asset identifier used across asset, quote, order, and position
requests.
example: 7453f146-b267-11f1-b4f4-0abd773ba497
symbol:
type: string
description: Asset symbol.
example: AAPLx
side:
type: string
enum:
- BUY
- SELL
- DEPOSIT
- WITHDRAWAL
description: >-
Order activity. Trade orders originate from quotes; deposit and
withdrawal records describe asset transfers.
example: BUY
status:
type: string
enum:
- PENDING
- SUCCESS
- FAILED
description: >-
Order processing state. Reconcile settled values only after
completion.
example: SUCCESS
network:
type: string
nullable: true
description: Network associated with execution or transfer, when available.
example: Ethereum
funding_currency:
type: string
description: Currency used to fund a trade. Null for asset-transfer records.
nullable: true
example: USDC
quoted_quantity:
type: string
pattern: ^-?[0-9]+(\.[0-9]+)?$
nullable: true
description: >-
Quantity from the accepted quote; null when the quote did not fix a
quantity or the record is an asset transfer.
example: '0.00297066689243735'
executed_quantity:
type: string
pattern: ^-?[0-9]+(\.[0-9]+)?$
nullable: true
description: Settled quantity for a completed trade; null before settlement.
example: '0.00297066689243735'
executed_price:
type: string
pattern: ^-?[0-9]+(\.[0-9]+)?$
nullable: true
description: >-
Settled trade price per unit in funding_currency. Not an
asset-transfer cost basis.
example: '336.624750000000055741'
cash_amount:
type: string
pattern: ^-?[0-9]+(\.[0-9]+)?$
nullable: true
description: >-
Settled trade amount before fees in funding_currency. Null before
settlement and for asset-transfer records.
example: '1'
fees:
type: array
items:
$ref: '#/components/schemas/Fee'
nullable: true
description: >-
Fees recorded on the completed order. Null means no settled fee
information is available.
example:
- type: TRADING
amount: '0.0005'
currency: USDC
total_amount:
type: string
pattern: ^-?[0-9]+(\.[0-9]+)?$
nullable: true
description: >-
Settled buy outlay including fees or sell proceeds after fees, in
funding_currency. Null before settlement and for asset transfers.
example: '1.0005'
transaction_hash:
type: string
nullable: true
description: >-
Public transaction hash when available. Null does not by itself
indicate that the order failed.
example: '0x7e7b7f06c0a4adce2ec2bc01b455fd4e014b9f298e7e2598b02c93dffa86a96f'
failure_code:
type: string
nullable: true
description: >-
Business failure identifier on a failed order. This is separate from
an HTTP error code.
failure_message:
type: string
nullable: true
description: >-
Human-readable explanation of an order failure; null when no failure
is reported.
created_at:
type: string
format: date-time
description: Time the order was created.
example: '2026-09-21T01:33:08.629Z'
updated_at:
type: string
format: date-time
description: Time the order was last updated.
example: '2026-09-21T01:50:53.855Z'
completed_at:
type: string
format: date-time
nullable: true
description: Settlement completion time; null until the order completes.
example: '2026-09-21T01:50:53.561Z'
failed_at:
type: string
format: date-time
nullable: true
description: Time of terminal failure; null when the order has not failed.
transfer_quantity:
type: string
pattern: ^-?[0-9]+(\.[0-9]+)?$
nullable: true
description: >-
Asset quantity for a deposit or withdrawal. Null for buy and sell
orders.
required:
- order_id
- quote_id
- client_reference
- asset_id
- symbol
- side
- status
- network
- funding_currency
- quoted_quantity
- executed_quantity
- executed_price
- cash_amount
- fees
- total_amount
- transaction_hash
- failure_code
- failure_message
- created_at
- updated_at
- completed_at
- failed_at
- transfer_quantity
Error:
type: object
additionalProperties: false
required:
- type
- code
- message
properties:
type:
type: string
description: Error category for classifying the failure.
pattern: ^[a-z][a-z0-9]*(_[a-z0-9]+)*$
code:
type: string
description: >-
Machine-readable business error code. Use this together with the
HTTP status; do not match on message text.
pattern: ^[a-z][a-z0-9]*(_[a-z0-9]+)*$
message:
type: string
description: Human-readable explanation of the error.
Fee:
type: object
additionalProperties: false
properties:
type:
type: string
enum:
- TRADING
- DEPOSIT
- WITHDRAWAL
description: Fee category.
example: TRADING
amount:
type: string
pattern: ^-?[0-9]+(\.[0-9]+)?$
description: Fee amount.
example: '0.0005'
currency:
type: string
description: Currency in which the fee is charged.
example: USDC
required:
- type
- amount
- currency
securitySchemes:
AuthToken:
type: apiKey
in: header
name: x-auth-token
description: The API token for login provided by UQPAY.
````