Authentication

Every /v1 request sends Authorization: Bearer and the API key. The API ignores cookies. It does not accept a browser call from another site. Put the key in the header only. Do not put it in a URL, a query string, a page, or a log you share.

Create and revoke keys at API keys.

The secret

The secret is shown once, when you create the key. Terminal stores a hash, a short prefix, and the last 4 characters.

Outside production the secret starts with tmk_test_. In production it starts with tmk_live_. After that prefix are 43 characters from this alphabet: digits, uppercase letters, and lowercase letters. A key from the other environment is refused.

last_used_at is written at most once a minute.

Who can create a key

Your email must be confirmed. The account must be under its plan's count of active keys. An account can create at most 10 keys a day. Revoking a key does not reset that day's count.

Creating a key stores the API terms version shown on that screen. The current version is a draft. Read Notice and terms.

Scopes

read is on every key. You choose the others when you create the key. Scopes cannot be changed later. Create a new key instead.

• Scope: read. What it allows: Every GET, a preview, and an explanation
• Scope: rules:write. What it allows: Create, change, pause, resume, and delete rules
• Scope: destinations:write. What it allows: Add, change, test, and delete webhook destinations
• Scope: services:write. What it allows: Sell alert services on the exchange, Terminal's marketplace for alert services, when it is open for the account
• Scope: subscriptions:write. What it allows: Subscribe to alert services on the exchange, when it is open for the account. Subscribing spends credits

A request outside the key's scopes returns 403 scope_missing and required_scope. Some changes stay on the signed-in Settings screen. Those return required_scope of session.

Caps

Each key has daily_cap_cents. You set it in whole dollars from $0 to $100 (0 to 10,000 cents). The default is $5 (500 cents). It caps the credits this key may spend in one UTC day: blocks, previews, and explanations together. $0 means the key does not spend credits. A key with only read can still spend credits on a preview, an explanation, or a block. The cap bounds that spend.

The account has monthly_spend_cap_cents. The default is $20 (2,000 cents). The maximum is $500 (50,000 cents). It caps API credit spend for the UTC month. Change it in Billing.

Revoking

Revoke takes effect on the next request: 401 invalid_key. A long-poll that is already open gets that 401 within 5 seconds. A revoked key stays on the list for 30 days, with revoked_at, and is then removed. Rename changes only the name.

The account object

GET /v1/account returns the plan, the limits, the credit balance in cents, the monthly cap, and the calling key. It does not return your email, your name, or a payment method.

Example. These are not live prices.

GET /v1/account HTTP/1.1
Authorization: Bearer $TERMINAL_API_KEY

HTTP/1.1 200 OK

{
  "account": {
    "plan": { "code": "pro", "name": "Pro" },
    "time_zone": "America/New_York",
    "monthly_spend_cap_cents": 2000,
    "credits": { "balance_cents": 0 },
    "features": { "webhooks": true },
    "limits": {
      "rules": 200,
      "watchlist_coins": 100,
      "history_days": 365,
      "api_keys": 10,
      "api_calls_per_month": 200000,
      "api_calls_per_minute": 300,
      "previews_per_day": 200,
      "webhook_destinations": 5,
      "notes_per_month": null,
      "notes_fair_use_per_month": 2000
    }
  },
  "key": {
    "name": "Reader",
    "scopes": ["read", "rules:write", "destinations:write"],
    "daily_cap_cents": 500,
    "prefix": "…",
    "last4": "…",
    "id": "…",
    "created_at": "…",
    "last_used_at": "…"
  }
}

features.webhooks is true when the plan's webhook destination limit is above zero. Pro is 5. Free and Trader are 0.

A missing key

No Authorization header, a header that is not Bearer, a malformed secret, an unknown secret, a revoked key, or a deleted account: 401 invalid_key. The response also sends WWW-Authenticate: Bearer realm="terminal", error="invalid_token".

Example. These are not live prices.

GET /v1/account HTTP/1.1

HTTP/1.1 401 Unauthorized

{
  "error": {
    "code": "invalid_key",
    "message": "This API key is not valid. Check the key, or create a new one in Settings."
  }
}

A key without the scope

Pause needs rules:write. A key with only read is refused. The rule stays as it was.

Example. These are not live prices.

POST /v1/rules/$RULE_ID/pause HTTP/1.1
Authorization: Bearer $TERMINAL_READ_KEY
Idempotency-Key: 6f1c0a2e-4b7d-4e3a-9c11-8a0d5e2b7f41

HTTP/1.1 403 Forbidden

{
  "error": {
    "code": "scope_missing",
    "required_scope": "rules:write",
    "message": "This API key cannot do this. Create a key that can create and change alert rules."
  }
}

Create a free account

Terminal reports market events for conditions you set. It does not tell you to buy, sell, or hold, and it does not place trades.