# Stepper Motor API
> Stepper-motor motion maths as an API, computed locally and deterministically — the steps-per-millimetre and speed numbers a 3D-printer, CNC or robotics builder configures a machine with. The leadscrew endpoint gives the steps per mm for a lead-screw or ball-screw axis: (motor steps per revolution × microstepping) ÷ the screw lead, so a 1.8° motor (200 steps) at 16 microsteps on an 8 mm-lead screw is 400 steps/mm with 2.5 µm of resolution — the value that goes straight into the firmware. The belt endpoint does the same for a belt-and-pulley axis, where the travel per motor turn is the pulley teeth × the belt pitch (GT2 belt = 2 mm), so a 20-tooth GT2 pulley gives the classic 80 steps/mm of a 3D-printer X/Y axis, and shows the speed-versus-precision trade of a bigger pulley. The speed endpoint turns a steps-per-mm and a step pulse rate into the axis speed in mm/s and mm/min — at 80 steps/mm a 40 kHz step rate is 500 mm/s, though the real limit is the motor stalling at high step rates and the controller pulse ceiling. It also notes that microstepping adds smoothness, not true accuracy, since torque per microstep falls. Everything is computed locally and deterministically, so it is instant and private. Ideal for 3D-printer and CNC firmware setup, motion-control and robotics tools, and maker calculators. Pure local computation — no key, no third-party service, instant. Ideal-geometry estimates — leave a margin below the theoretical top speed. 3 compute endpoints. For CNC surface finish use a CNC-finish API; for gear ratios a gear-ratio API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/steppermotor-api/..."
```

## Pricing
- **Free** (Free) — 7,600 calls/Mo, 2 req/s
- **Starter** ($8/Mo) — 80,000 calls/Mo, 6 req/s
- **Pro** ($29/Mo) — 330,000 calls/Mo, 15 req/s
- **Mega** ($87/Mo) — 1,540,000 calls/Mo, 40 req/s

## Endpoints

### Motion

#### `GET /v1/belt` — Steps per mm for a belt axis

**Parameters:**
- `pulley_teeth` (query, required, string) — Pulley tooth count Example: `20`
- `belt_pitch_mm` (query, optional, string) — Belt pitch (mm, GT2=2, default 2) Example: `2`
- `motor_steps_per_rev` (query, optional, string) — Motor steps per rev (default 200) Example: `200`
- `microstepping` (query, optional, string) — Microstepping (default 16) Example: `16`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/steppermotor-api/v1/belt?pulley_teeth=20&belt_pitch_mm=2&motor_steps_per_rev=200&microstepping=16"
```

**Response:**
```json
{
    "data": {
        "note": "For a belt drive the travel per motor revolution = pulley teeth × belt pitch (GT2 belt = 2 mm), so steps per mm = (motor steps × microstepping) ÷ that. A 1.8° motor at 16 microsteps on a 20-tooth GT2 pulley gives 80 steps/mm — the classic 3D-printer X/Y value. A bigger pulley moves faster but coarsens resolution; that is the speed-versus-precision trade every belt axis makes.",
        "inputs": {
            "pulley_teeth": 20,
            "belt_pitch_mm": 2,
            "microstepping": 16,
            "motor_steps_per_rev": 200
        },
        "steps_per_mm": 80,
        "resolution_um": 12.5,
        "travel_per_rev_mm": 40
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:52.398Z",
        "request_id": "ef841f3b-68c9-4d5e-a765-68914610f140"
    },
    "status": "ok",
    "message": "Belt steps/mm",
    "success": true
}
```

#### `GET /v1/leadscrew` — Steps per mm for a lead-screw axis

**Parameters:**
- `lead_mm` (query, required, string) — Screw lead — travel per revolution (mm) Example: `8`
- `motor_steps_per_rev` (query, optional, string) — Motor steps per rev (default 200) Example: `200`
- `microstepping` (query, optional, string) — Microstepping (default 16) Example: `16`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/steppermotor-api/v1/leadscrew?lead_mm=8&motor_steps_per_rev=200&microstepping=16"
```

**Response:**
```json
{
    "data": {
        "note": "Steps per mm = (motor steps per rev × microstepping) ÷ the screw lead (travel per turn). A 1.8° motor (200 steps) at 16 microsteps on an 8 mm-lead screw gives 400 steps/mm and 2.5 µm of resolution. Microstepping smooths motion and raises the count but does not add real accuracy — torque per microstep drops, so the true positioning still rests on the motor, screw and mechanics. Beware confusing lead with pitch on a multi-start screw.",
        "inputs": {
            "lead_mm": 8,
            "microstepping": 16,
            "motor_steps_per_rev": 200
        },
        "steps_per_mm": 400,
        "resolution_um": 2.5,
        "full_steps_per_mm": 25
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:52.499Z",
        "request_id": "ed8868f8-1d95-4be7-a229-1c6bf8c505d5"
    },
    "status": "ok",
    "message": "Leadscrew steps/mm",
    "success": true
}
```

#### `GET /v1/speed` — Axis speed from the step rate

**Parameters:**
- `steps_per_mm` (query, required, string) — Steps per mm Example: `80`
- `step_frequency_hz` (query, required, string) — Step pulse rate (Hz) Example: `40000`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/steppermotor-api/v1/speed?steps_per_mm=80&step_frequency_hz=40000"
```

**Response:**
```json
{
    "data": {
        "note": "Axis speed = step pulse rate ÷ steps per mm, so the same controller step-rate ceiling gives a faster axis when steps/mm is lower. At 80 steps/mm a 40 kHz step rate is 500 mm/s — but real top speed is limited first by the motor losing torque at high step rates and stalling, and by the controller's maximum pulse frequency, so leave a margin below the theoretical figure.",
        "inputs": {
            "steps_per_mm": 80,
            "step_frequency_hz": 40000
        },
        "speed_mm_s": 500,
        "speed_mm_min": 30000
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:52.573Z",
        "request_id": "7fc33fc8-c2e0-4d59-adc0-d66e64ec0439"
    },
    "status": "ok",
    "message": "Axis speed",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/steppermotor-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "notes": "Metric (mm, µm, Hz, mm/s). Lead-screw: steps/mm = (steps×microstep)/lead; belt: ÷(teeth×pitch); speed = step Hz ÷ steps/mm. Microstepping adds smoothness, not accuracy. For CNC surface finish use a CNC-finish API; for gear ratios a gear-ratio API.",
        "service": "steppermotor-api",
        "endpoints": {
            "GET /v1/belt": "Steps per mm for a belt-and-pulley axis.",
            "GET /v1/meta": "This document.",
            "GET /v1/speed": "Axis speed from steps-per-mm and the step pulse rate.",
            "GET /v1/leadscrew": "Steps per mm for a lead-screw/ball-screw axis."
        },
        "description": "Stepper-motor motion maths: steps-per-mm for lead-screw and belt axes, and axis speed from the step rate."
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:52.643Z",
        "request_id": "80b25329-e658-4840-a775-45bec706606f"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/steppermotor-api
OpenAPI spec: https://www.oanor.com/api/steppermotor-api/openapi.json