Create Scheduled Order | Bitnob API Reference

Create Scheduled Order (DCA)

Use Case

Create a recurring buy that fires on a fixed frequency — daily, weekly, or monthly — at a specific execution_time. Standard pattern for dollar-cost averaging (DCA): set a fixed amount in the smallest unit of the target currency, choose a cadence, and let the engine run the order at each tick.

Create Scheduled Order

Request Body

currencystringRequired

Asset being bought on each execution (e.g. 'BTC').

quote_currencystringRequired

Currency paying for each tick (e.g. 'USDT', 'USDC').

amountstringRequired

Amount to spend per execution, expressed as an integer string in the smallest unit of quote_currency (e.g. '50000000' on a USDT pair = 50 USDT per tick for 6-decimal minor units).

frequencystringRequired

How often to execute. One of 'daily', 'weekly', or 'monthly'.

execution_timestringRequired

Time of day (UTC) when each execution fires, in 'HH:MM' 24-hour format (e.g. '09:00').

day_of_weeknumberConditional

Required for 'weekly' frequency. 0 = Sunday … 6 = Saturday. Ignored for daily/monthly — pass 0.

day_of_monthnumberConditional

Required for 'monthly' frequency. 1–28 recommended (values 29–31 skip months without that day). Ignored for daily/weekly — pass 0.

referencestringOptional

Client-generated identifier for idempotency and internal tracking.

Unused `day_of_*` Fields

The API requires both day_of_week and day_of_month on every request, but ignores the one that doesn't apply to your chosen frequency. Pass 0 for the unused field.

Sample Request

Sample Response

List Scheduled Orders

Use Case

Return all scheduled orders for your company. Filter by status (active, paused, cancelled, completed) to show only the ones that matter on your dashboard.

List Scheduled Orders

Query Parameters

statusstringOptional

Filter by lifecycle state: 'active', 'paused', 'cancelled', 'completed'.

Response Fields

data.schedulesArray<Schedule>

Every scheduled order for your company. Each entry uses the same shape returned by Create Scheduled Order — refer to that section for per-field docs.

data.schedules[].total_executionsNumber

Count of ticks that have fired so far.

data.schedules[].total_amount_spentString

Cumulative quote-currency amount deducted across all executions (smallest unit).

data.schedules[].total_quantity_acquiredString

Cumulative base-asset quantity acquired across all executions.

data.schedules[].last_executed_atString

RFC 3339 / ISO 8601 timestamp of the most recent tick. Empty string on schedules that haven't fired yet.

Sample Response

Update Scheduled Order

Use Case

Adjust a recurring order in place without cancelling and re-creating it. Common uses: pause/resume (status: "paused" / "active"), change the per-tick amount, or shift execution_time. Fields omitted from the request are left untouched; next_execution_at is only recomputed when you change the cadence anchors (frequency, day_of_week, day_of_month, execution_time).

Update Scheduled Order

Body Parameters

amountStringOptional

New per-tick spend in the smallest unit of quote_currency. Takes effect on the next execution.

frequencyStringOptional

New cadence: 'daily', 'weekly', or 'monthly'. Changing this resets next_execution_at.

day_of_weekIntegerOptional

0–6 (Sunday=0). Only meaningful when frequency is 'weekly'.

day_of_monthIntegerOptional

1–31. Only meaningful when frequency is 'monthly'.

execution_timeStringOptional

24-hour HH:MM firing time in UTC. Changing this reschedules next_execution_at.

statusStringOptional

'paused' to stop future executions without cancelling, or 'active' to resume a paused schedule.

Pausing a Schedule

Setting status: "paused" freezes future executions but keeps the schedule on record — resume it at any time by sending another update with status: "active". next_execution_at is preserved, so the schedule picks up from where it left off.

Response Fields

successBoolean

Flag indicating the update was applied.

messageString

Human-readable status message.

data.scheduleObject

The updated schedule record. Shape is identical to Get Scheduled Order.

metadata.request_idString

Unique request identifier for support and tracing.

timestampDate

Server time when the response was generated.

Sample Request

Sample Response

Get Scheduled Order Executions

Use Case

Return the execution history for a scheduled order — one entry per cadence tick, with the fill price, quantity, and link to the underlying order. Drives progress charts and reconciliation.

Get Scheduled Order Executions

Response Fields

data.executionsArray<Execution>

Per-tick execution records, ordered newest first.

data.executions[].idUUID

Execution identifier.

data.executions[].order_idUUID

ID of the underlying order created for this tick (usable with Get Order by ID).

data.executions[].statusString

'completed', 'failed', or 'skipped'.

data.executions[].quantityString

Base-asset amount purchased / sold on this tick.

data.executions[].priceString

Fill price for this tick.

data.executions[].quote_amountString

Quote-currency amount spent (for buys) or received (for sells).

data.executions[].executed_atDate

RFC 3339 / ISO 8601 timestamp of when this tick ran.

Sample Response