Skip to content
API · v1

Run everything through the API

List and rotate your proxies, place and renew orders from your wallet or credit line, check your balance, and get signed webhooks when things happen. Plain HTTP, no SDK required — and retries can never double-charge you thanks to idempotency keys.

Rotation & status base
https://api.tmpx.io
REST API base
https://app.trumpproxies.com

Machine-readable: OpenAPI 3.1 spec (import into Postman/Insomnia or hand to an AI agent) · llms.txt · llms-full.txt (the whole reference as one markdown file for AI agents)

Authentication

Every /api/v1 request carries a Bearer key minted in your portal (shown once, stored hashed). Keys carry scopes — grant each integration only what it needs. Placing orders and renewals ( orders:write) moves money, so it's enabled per account — contact support to switch it on. Rotation links and the status endpoint need no key: the token itself is the secret.

Authorization: Bearer tp_live_…

Idempotency — retries never double-charge

POST /api/v1/orders requires an Idempotency-Key header: a unique string per distinct order (a UUID is perfect). If a request times out or your connection drops, retry with the same key — you'll get the original outcome back (Idempotent-Replay: true), and your wallet is charged at most once. Reusing a key with different parameters returns 422; keys are kept for 24 hours.

# safe to run twice — the second call replays the first result
curl -X POST -H "Authorization: Bearer tp_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"plan_id":"eu-full-access","location":"de"}]}' \
  https://app.trumpproxies.com/api/v1/orders

Rate limits & errors

120 requests/minute per key — a 429 carries Retry-After. Ordering additionally has a per-request cap (10 proxies) and a daily cap (25 proxies by default; ask us to raise it). Errors are always { "error": "human-readable message" } with a conventional status: 400 invalid input · 401 bad key · 402 insufficient balance/credit · 403 missing scope · 404 not yours / not found · 409 in-flight idempotency conflict · 422 key reused with different params · 429 rate/cap.

Order statuses

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

  • pendingCreated, awaiting payment
  • paidPayment settled — provisioning is starting
  • provisioningProxies are being created
  • completedProvisioned — credentials are in the order detail (and your email)
  • processingBeing completed by our team — no action needed, poll again later
  • cancelledCancelled before payment
  • refundedRefunded

Webhooks — signed, retried, verifiable

Register an HTTPS endpoint and we'll POST you events: order.completed, order.processing, proxy.expiring_soon (≤72h left), proxy.renewed. Payloads carry ids and status — fetch detail through the API. Failed deliveries retry with backoff (1m → 12h, ~15h total); 8 consecutive failures disable the endpoint. Every delivery is signed:

POST https://your-app.example.com/hooks/tp
X-TP-Event: order.completed
X-TP-Delivery-Id: 6b2e…
X-TP-Signature: t=1752400000,v1=<hex hmac-sha256(secret, "<t>.<raw body>")>

{ "id": "6b2e…", "event": "order.completed", "created_at": "…", "data": { "order_id": "…", "order_number": "TPX-…", "status": "completed" } }

Verify with a timing-safe compare (Node example):

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));
}
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.

Auth: None — the token in your credential email is the secret

Errors

  • 404 unknown_tokenThe token doesn't match any proxy
  • 403 expired / suspended / not_rotatableThe proxy can't rotate right now (plan or state)
  • 503 offlineThe line is temporarily offline — try again shortly
  • 502 errorRotation failed upstream — retry, then contact support

Request

curl https://api.tmpx.io/api/rotate/YOUR_TOKEN

Response · 200

{
  "ok": true,
  "status": "rotating",
  "message": "✅ Your IP is being updated."
}
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.

Auth: None — token-scoped

Errors

  • 404Unknown token

Request

curl https://api.tmpx.io/api/proxy/YOUR_TOKEN/status

Response · 200

{
  "ok": true,
  "host": "…",
  "port": 8041,
  "status": "active",
  "currentIp": "100.66.…",
  "expiresAt": "2026-08-01T00:00:00.000Z",
  "secondsLeft": 2591999
}
GET/api/v1/accountscope: account:read

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.

Auth: Authorization: Bearer tp_live_…

Errors

  • 401 / 403 / 429Auth, scope or rate-limit
  • 403Not available for reseller sub-accounts

Request

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

Response · 200

{
  "balance": -120.00,
  "credit_limit": 750.00,
  "owed": 120.00,
  "currency": "USD"
}
GET/api/v1/ordersscope: orders:read

List your orders

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

Auth: Authorization: Bearer tp_live_…

Query params

  • limitPage size, 1–100 (default 20)
  • created_beforeISO 8601 timestamp — pages backwards through older orders

Errors

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

Request

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

Response · 200

{
  "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
}
GET/api/v1/orders/{id}scope: orders:read

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.

Auth: Authorization: Bearer tp_live_…

Errors

  • 404Order not found on your account
  • 401 / 403 / 429Auth, scope or rate-limit

Request

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

Response · 200

{
  "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/…"
    }
  ]
}
POST/api/v1/ordersIdempotency-Keyscope: orders:write

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.

Auth: Authorization: Bearer tp_live_…

Errors

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

Request body

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

Request

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

{
  "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/…"
    }
  ]
}
GET/api/v1/proxiesscope: proxies:read

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.

Auth: Authorization: Bearer tp_live_…

Query params

  • statusOptional filter: active, expired, suspended, offline or pending

Errors

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

Request

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

Response · 200

{
  "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/…"
    }
  ]
}
POST/api/v1/proxies/{id}/rotatescope: proxies:write

Rotate a proxy by ID

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

Auth: Authorization: Bearer tp_live_…

Errors

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

Request

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

Response · 200

{ "ok": true, "message": "…" }
POST/api/v1/proxies/{id}/renewscope: orders:write

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. Charge-first with automatic refund if the extension can't be applied.

Auth: Authorization: Bearer tp_live_…

Errors

  • 400Proxy isn't active / can't self-renew — contact support
  • 402Insufficient wallet balance / credit
  • 404Proxy not found on your account
  • 502Renewal couldn't be applied — any charge is auto-refunded; retry shortly

Request

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

Response · 200

{
  "ok": true,
  "new_expires_at": "2026-09-12T00:00:00.000Z",
  "charged_usd": 20.00
}
POST/api/v1/proxies/{id}/auto-renewscope: proxies:write

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.

Auth: Authorization: Bearer tp_live_…

Errors

  • 400Body must be {enabled: true|false}
  • 404Proxy not found on your account

Request body

{ "enabled": false }

Request

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

{ "ok": true, "auto_renew": false }
GET/api/v1/webhooksscope: webhooks:manage

List webhook endpoints

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

Auth: Authorization: Bearer tp_live_…

Errors

  • 401 / 403 / 429Auth, scope or rate-limit

Request

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

Response · 200

{
  "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"]
}
POST/api/v1/webhooksscope: webhooks:manage

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.

Auth: Authorization: Bearer tp_live_…

Errors

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

Request body

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

Request

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

{
  "id": "…",
  "url": "https://your-app.example.com/hooks/tp",
  "events": ["order.completed"],
  "secret": "whsec_…",
  "created_at": "2026-07-13T10:00:00.000Z"
}
DELETE/api/v1/webhooks/{id}scope: webhooks:manage

Delete a webhook endpoint

Removes the endpoint; queued deliveries to it are dropped.

Auth: Authorization: Bearer tp_live_…

Errors

  • 404Webhook not found on your account

Request

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

Response · 200

{ "ok": true }
GET/api/v1/resellerscope: resellers:read

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.

Auth: Authorization: Bearer tp_live_…

Errors

  • 403Not an active reseller

Request

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

Response · 200

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

Changelog

  • 2026-07-13v1 launch: orders (idempotent), renewals, auto-renew, account balance, signed webhooks, OpenAPI 3.1 spec, llms.txt/llms-full.txt. GET /proxies gains rotation_url, auto_renew and a ?status= filter.
  • 2026-06-26Token endpoints hardened: per-IP limits on rotation/status; rotation accepted at most once per 5 minutes per proxy.

Next

Keys live in your portal

Create scoped keys, watch usage, and revoke anything you no longer trust — in seconds.

Manage API keysSetup guide