# Trump Proxies — full API reference (llms-full.txt)

> Complete REST API reference for Trump Proxies 4G mobile proxies, as one markdown file for
> AI agents and developers. Human version: https://trumpproxies.com/docs/api · Machine spec:
> https://app.trumpproxies.com/api/v1/openapi.json · Index: https://trumpproxies.com/llms.txt

## Basics

- Authenticated base URL: `https://app.trumpproxies.com` — send `Authorization: Bearer tp_live_…` (keys are minted in the customer portal under API keys; shown once, stored hashed).
- Token endpoints (rotation/status) need no key — the token itself is the secret: `https://api.tmpx.io`.
- Rate limit: 120 requests/minute per key (429 + Retry-After). Ordering also has a per-request cap (10 proxies) and a daily cap (25 proxies by default; raisable per account).
- Placing orders and renewals moves money, so the `orders:write` scope is enabled per account by support; all other scopes are self-serve.
- Errors are always `{ "error": "human-readable message" }` with conventional statuses: 400 invalid input · 401 bad key · 402 insufficient balance/credit · 403 missing scope · 404 not found on your account · 409 in-flight idempotency conflict · 422 idempotency key reused with different params · 429 rate/cap.

## Idempotency (POST /api/v1/orders)

Send an `Idempotency-Key` header (a UUID is perfect) with every order. Retries with the same key replay the original response (`Idempotent-Replay: true`) — the wallet is charged at most once. Reusing a key with different parameters returns 422. Keys are kept for 24 hours.

## Order statuses

- `pending` — Created, awaiting payment
- `paid` — Payment settled — provisioning is starting
- `provisioning` — Proxies are being created
- `completed` — Provisioned — credentials are in the order detail (and your email)
- `processing` — Being completed by our team — no action needed, poll again later
- `cancelled` — Cancelled before payment
- `refunded` — Refunded

Poll `GET /api/v1/orders/{id}` until `completed` — the `proxies` array then carries full credentials and rotation links.

## Webhooks

Register an HTTPS endpoint (`POST /api/v1/webhooks`) for events: `order.completed`, `order.processing`, `proxy.expiring_soon` (≤72h left), `proxy.renewed`. Payloads carry ids + status only — fetch detail through the API. Deliveries retry with backoff (1m → 12h); 8 consecutive failures disable the endpoint (delete + re-register to recover). Every delivery is signed: `X-TP-Signature: t=<unix>,v1=<hex hmac-sha256(secret, "<t>.<raw body>")>` — verify with a timing-safe compare and reject |now − t| > 300s:

```js
import crypto from "node:crypto";

export function verifyTpSignature(rawBody, header, secret, toleranceSec = 300) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? "");
  if (!m) return false;
  const [_, t, sig] = m;
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false; // replay window
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}
```

## Endpoints

### GET /api/rotate/{token}

**Rotate your proxy's IP.** Requests a fresh IP for the proxy behind the token. Rotations are accepted at most once per 5 minutes per proxy; any ok:true response means your IP refresh is in progress. Works from a browser, curl, or any scheduler.

- Base: `https://api.tmpx.io`
- Auth: None — the token in your credential email is the secret

Example:
```bash
curl https://api.tmpx.io/api/rotate/YOUR_TOKEN
```

Response (200):
```json
{
  "ok": true,
  "status": "rotating",
  "message": "✅ Your IP is being updated."
}
```

Errors:
- `404 unknown_token` — The token doesn't match any proxy
- `403 expired / suspended / not_rotatable` — The proxy can't rotate right now (plan or state)
- `503 offline` — The line is temporarily offline — try again shortly
- `502 error` — Rotation failed upstream — retry, then contact support

---

### GET /api/proxy/{token}/status

**Check a proxy's status.** Live status for the proxy behind the token: state, endpoint, current IP where available, and time left on the term. Poll it from monitors or dashboards.

- Base: `https://api.tmpx.io`
- Auth: None — token-scoped

Example:
```bash
curl https://api.tmpx.io/api/proxy/YOUR_TOKEN/status
```

Response (200):
```json
{
  "ok": true,
  "host": "…",
  "port": 8041,
  "status": "active",
  "currentIp": "100.66.…",
  "expiresAt": "2026-08-01T00:00:00.000Z",
  "secondsLeft": 2591999
}
```

Errors:
- `404` — Unknown token

---

### GET /api/v1/account

**Account balance & credit.** Your wallet balance, credit limit and the amount currently owed (how far the balance is into the credit line). The numbers your ordering automation should check before placing orders.

- Base: `https://app.trumpproxies.com`
- Auth: Authorization: Bearer tp_live_… (scope `account:read`)

Example:
```bash
curl -H "Authorization: Bearer tp_live_…" \
  https://app.trumpproxies.com/api/v1/account
```

Response (200):
```json
{
  "balance": -120.00,
  "credit_limit": 750.00,
  "owed": 120.00,
  "currency": "USD"
}
```

Errors:
- `401 / 403 / 429` — Auth, scope or rate-limit
- `403` — Not available for reseller sub-accounts

---

### GET /api/v1/orders

**List your orders.** Your orders, newest first. Statuses use the API vocabulary below — poll an individual order for its proxies once it's completed.

- Base: `https://app.trumpproxies.com`
- Auth: Authorization: Bearer tp_live_… (scope `orders:read`)
- Query params:
  - `limit` — Page size, 1–100 (default 20)
  - `created_before` — ISO 8601 timestamp — pages backwards through older orders

Example:
```bash
curl -H "Authorization: Bearer tp_live_…" \
  "https://app.trumpproxies.com/api/v1/orders?limit=20"
```

Response (200):
```json
{
  "orders": [
    {
      "id": "…",
      "order_number": "TPX-…",
      "status": "completed",
      "total_usd": 40.00,
      "line_items": [
        { "plan_id": "eu-full-access", "title": "Full Access", "quantity": 2, "location": "de", "unit_price": 20.00 }
      ],
      "placed_at": "2026-07-13T10:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_created_before": null
}
```

Errors:
- `400` — created_before is not a valid ISO 8601 timestamp
- `401 / 403 / 429` — Auth, scope or rate-limit

---

### GET /api/v1/orders/{id}

**Get one order (with credentials).** One order including its provisioned proxies with full connection details and rotation links. This is the endpoint to poll after placing an order — proxies appear as provisioning completes.

- Base: `https://app.trumpproxies.com`
- Auth: Authorization: Bearer tp_live_… (scope `orders:read`)

Example:
```bash
curl -H "Authorization: Bearer tp_live_…" \
  https://app.trumpproxies.com/api/v1/orders/ORDER_ID
```

Response (200):
```json
{
  "id": "…",
  "order_number": "TPX-…",
  "status": "completed",
  "total_usd": 40.00,
  "line_items": [
    { "plan_id": "eu-full-access", "title": "Full Access", "quantity": 2, "location": "de", "unit_price": 20.00 }
  ],
  "placed_at": "2026-07-13T10:00:00.000Z",
  "proxies": [
    {
      "id": "…",
      "type": "proxy",
      "status": "active",
      "host": "…",
      "port": 8041,
      "username": "…",
      "password": "…",
      "protocol": "both",
      "ip_version": "v64",
      "expires_at": "2026-08-13T00:00:00.000Z",
      "auto_renew": false,
      "rotation_url": "https://api.tmpx.io/api/rotate/…"
    }
  ]
}
```

Errors:
- `404` — Order not found on your account
- `401 / 403 / 429` — Auth, scope or rate-limit

---

### POST /api/v1/orders

**Place an order.** Places a wallet/credit-paid order and provisions it — your custom pricing applies automatically. Requires the orders:write scope (enabled per account — contact support) and an Idempotency-Key header: retries with the same key can NEVER double-charge; you get the original response back. Up to 10 proxies per request and 25 per day by default. Credentials are returned in the response once provisioning completes (usually within the request) and also emailed.

- Base: `https://app.trumpproxies.com`
- Auth: Authorization: Bearer tp_live_… (scope `orders:write`)
- Requires an `Idempotency-Key` header (unique per distinct order; retries replay the original response and never double-charge).

Request body:
```json
{
  "items": [
    { "plan_id": "eu-full-access", "quantity": 2, "location": "de", "platform": "instagram" }
  ]
}
```

Example:
```bash
curl -X POST \
  -H "Authorization: Bearer tp_live_…" \
  -H "Idempotency-Key: 2f4a9c1e-order-42" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"plan_id":"eu-full-access","quantity":2,"location":"de","platform":"instagram"}]}' \
  https://app.trumpproxies.com/api/v1/orders
```

Response (201):
```json
{
  "id": "…",
  "order_number": "TPX-…",
  "status": "completed",
  "total_usd": 40.00,
  "line_items": [
    { "plan_id": "eu-full-access", "title": "Full Access", "quantity": 2, "location": "de", "unit_price": 20.00 }
  ],
  "placed_at": "2026-07-13T10:00:00.000Z",
  "proxies": [
    {
      "id": "…",
      "type": "proxy",
      "status": "active",
      "host": "…",
      "port": 8041,
      "username": "…",
      "password": "…",
      "protocol": "both",
      "ip_version": "v64",
      "expires_at": "2026-08-13T00:00:00.000Z",
      "auto_renew": false,
      "rotation_url": "https://api.tmpx.io/api/rotate/…"
    }
  ]
}
```

Errors:
- `400` — Missing Idempotency-Key, unknown plan, missing option, >10 proxies, or invalid JSON
- `402` — Insufficient wallet balance / credit — top up or contact support
- `409` — Same key currently in flight (retry shortly) — or its original attempt failed (use a new key)
- `422` — Idempotency-Key reused with different parameters
- `429` — Rate limit or your daily order cap reached
- `401 / 403` — Auth or scope (orders:write is enabled per account)

---

### GET /api/v1/proxies

**List your proxies.** Every proxy on your account with connection details, protocol, IP version, expiry, auto-renew state and its rotation link. Mint API keys in the portal under API keys; keys are rate-limited to 120 requests/minute.

- Base: `https://app.trumpproxies.com`
- Auth: Authorization: Bearer tp_live_… (scope `proxies:read`)
- Query params:
  - `status` — Optional filter: active, expired, suspended, offline or pending

Example:
```bash
curl -H "Authorization: Bearer tp_live_…" \
  https://app.trumpproxies.com/api/v1/proxies
```

Response (200):
```json
{
  "proxies": [
    {
      "id": "…",
      "type": "proxy",
      "status": "active",
      "host": "…",
      "port": 8041,
      "username": "…",
      "password": "…",
      "protocol": "both",
      "ip_version": "v64",
      "expires_at": "2026-08-01T00:00:00.000Z",
      "auto_renew": false,
      "rotation_url": "https://api.tmpx.io/api/rotate/…"
    }
  ]
}
```

Errors:
- `401` — Missing or invalid API key
- `403` — Key lacks the proxies:read scope
- `429` — Rate limit exceeded — respect Retry-After

---

### POST /api/v1/proxies/{id}/rotate

**Rotate a proxy by ID.** Programmatic rotation for a specific proxy. The same 5-minute acceptance window applies as the rotation link.

- Base: `https://app.trumpproxies.com`
- Auth: Authorization: Bearer tp_live_… (scope `proxies:write`)

Example:
```bash
curl -X POST -H "Authorization: Bearer tp_live_…" \
  https://app.trumpproxies.com/api/v1/proxies/PROXY_ID/rotate
```

Response (200):
```json
{ "ok": true, "message": "…" }
```

Errors:
- `400` — This proxy's plan doesn't support rotation
- `404` — Proxy not found on your account
- `401 / 403 / 429` — Auth, scope or rate-limit — as above

---

### POST /api/v1/proxies/{id}/renew

**Renew a proxy (+30 days).** In-place renewal funded from your wallet/credit line — same proxy, same IP, port and credentials, at your usual price. Expired proxies can still be renewed for up to 14 days after expiry (the line reactivates in place; the new term starts the day you renew). Charge-first with automatic refund if the extension can't be applied.

- Base: `https://app.trumpproxies.com`
- Auth: Authorization: Bearer tp_live_… (scope `orders:write`)

Example:
```bash
curl -X POST -H "Authorization: Bearer tp_live_…" \
  https://app.trumpproxies.com/api/v1/proxies/PROXY_ID/renew
```

Response (200):
```json
{
  "ok": true,
  "new_expires_at": "2026-09-12T00:00:00.000Z",
  "charged_usd": 20.00
}
```

Errors:
- `400` — Expired more than 14 days ago (place a new order) / can't self-renew — contact support
- `402` — Insufficient wallet balance / credit
- `404` — Proxy not found on your account
- `502` — Renewal couldn't be applied — any charge is auto-refunded; retry shortly

---

### POST /api/v1/proxies/{id}/auto-renew

**Turn auto-renew on / off.** enabled:true keeps the line renewing from your wallet before expiry; enabled:false is the API's cancel — the line simply runs out its paid term and is never charged again.

- Base: `https://app.trumpproxies.com`
- Auth: Authorization: Bearer tp_live_… (scope `proxies:write`)

Request body:
```json
{ "enabled": false }
```

Example:
```bash
curl -X POST -H "Authorization: Bearer tp_live_…" \
  -H "Content-Type: application/json" -d '{"enabled":false}' \
  https://app.trumpproxies.com/api/v1/proxies/PROXY_ID/auto-renew
```

Response (200):
```json
{ "ok": true, "auto_renew": false }
```

Errors:
- `400` — Body must be {enabled: true|false}
- `404` — Proxy not found on your account

---

### GET /api/v1/webhooks

**List webhook endpoints.** Your registered webhook endpoints and the available event types. Secrets are never returned after creation.

- Base: `https://app.trumpproxies.com`
- Auth: Authorization: Bearer tp_live_… (scope `webhooks:manage`)

Example:
```bash
curl -H "Authorization: Bearer tp_live_…" \
  https://app.trumpproxies.com/api/v1/webhooks
```

Response (200):
```json
{
  "webhooks": [
    {
      "id": "…",
      "url": "https://your-app.example.com/hooks/tp",
      "events": ["order.completed", "proxy.expiring_soon"],
      "disabled": false,
      "last_success_at": "2026-07-13T10:00:00.000Z",
      "created_at": "2026-07-01T00:00:00.000Z"
    }
  ],
  "events": ["order.completed", "order.processing", "proxy.expiring_soon", "proxy.renewed"]
}
```

Errors:
- `401 / 403 / 429` — Auth, scope or rate-limit

---

### POST /api/v1/webhooks

**Register a webhook endpoint.** Register an HTTPS endpoint for event notifications. The signing secret is returned ONCE in this response — store it and verify every delivery (see Webhooks below). Deliveries retry with backoff for ~15h; an endpoint failing 8 deliveries in a row is disabled.

- Base: `https://app.trumpproxies.com`
- Auth: Authorization: Bearer tp_live_… (scope `webhooks:manage`)

Request body:
```json
{
  "url": "https://your-app.example.com/hooks/tp",
  "events": ["order.completed", "proxy.expiring_soon"]
}
```

Example:
```bash
curl -X POST -H "Authorization: Bearer tp_live_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.example.com/hooks/tp","events":["order.completed"]}' \
  https://app.trumpproxies.com/api/v1/webhooks
```

Response (200):
```json
{
  "id": "…",
  "url": "https://your-app.example.com/hooks/tp",
  "events": ["order.completed"],
  "secret": "whsec_…",
  "created_at": "2026-07-13T10:00:00.000Z"
}
```

Errors:
- `400` — URL must be https and publicly reachable; events must be from the list; max 5 endpoints
- `401 / 403 / 429` — Auth, scope or rate-limit

---

### DELETE /api/v1/webhooks/{id}

**Delete a webhook endpoint.** Removes the endpoint; queued deliveries to it are dropped.

- Base: `https://app.trumpproxies.com`
- Auth: Authorization: Bearer tp_live_… (scope `webhooks:manage`)

Example:
```bash
curl -X DELETE -H "Authorization: Bearer tp_live_…" \
  https://app.trumpproxies.com/api/v1/webhooks/WEBHOOK_ID
```

Response (200):
```json
{ "ok": true }
```

Errors:
- `404` — Webhook not found on your account

---

### GET /api/v1/reseller

**Reseller: list sub-accounts.** For active resellers: your tier plus every sub-account and its proxies — the data behind your own storefront or billing automation.

- Base: `https://app.trumpproxies.com`
- Auth: Authorization: Bearer tp_live_… (scope `resellers:read`)

Example:
```bash
curl -H "Authorization: Bearer tp_live_…" \
  https://app.trumpproxies.com/api/v1/reseller
```

Response (200):
```json
{
  "tier": "volume",
  "sub_accounts": [
    {
      "id": "…",
      "email": "customer@…",
      "name": "…",
      "proxies": [{ "id": "…", "type": "proxy", "status": "active", "host": "…", "port": 8042, "expires_at": "…" }]
    }
  ]
}
```

Errors:
- `403` — Not an active reseller