Vectr
Learn

API keys: what a leaked one can cost

An API key lets a script or an agent act as your Vectr wallet, and its scope decides whether a leak costs you data or money. This guide is the exact surface each scope reaches, the restrictions a key can carry, how to revoke and rotate one, and a checklist for running an agent with a read-write key. Scopes are read from GET /config; the rules from the backend source.

Updated

Surface

The four routes a key opens

Everything an API key can reach. Scopes on this deployment right now:

read-onlyread-writeip-allowlistrecipient-allowlist

Everything else is either public and needs no key (tokens, quotes, trades, candles, /config) or takes a signed-in session that no key can stand in for: creating and revoking keys, the wallet's security settings, the /orders endpoints and key export. The wallet a key acts for, and whether it is read-only, come from the key itself; nothing in a request body can claim either. The API's global limit of 200 requests per 60 seconds per client applies to keys too. Header formats and error codes are in the authentication reference.

If it leaks

What each scope can and cannot do

read-only
Costs you data, and credits
Can
  • Run agent jobs as your wallet, and read what the agent can: portfolio, orders, trade history, creator fees and the agent's saved memories
  • Build unsigned transactions, which this key can never submit
  • Spend your AI credits, and trigger an auto top-up if you turned it on, within its daily cap
  • Cancel your agent jobs that are still pending
Cannot
  • Submit anything: the signing route answers 403
  • Create or cancel limit, stop, DCA or TWAP orders
  • Turn auto top-up on or change it
  • Change security settings, create or revoke keys, or export the wallet key
read-write
Costs you what the wallet holds, inside your rules
Can
  • Everything a read-only key can
  • Submit transactions from your Vectr wallet with no person in the loop, up to 20 a minute
  • Create limit, stop, DCA and TWAP orders on a Pro wallet, which keep filling after the key is revoked until you cancel them
  • Turn on auto top-up of AI credits
Cannot
  • Get past the calldata whitelist, its own recipient list or your wallet rules
  • Change those rules or lift the pause switch
  • Create or revoke keys, or export the wallet key
A read-write API key is the automation path: it can submit transactions from your Vectr wallet without a person in the loop, inside the key's limits. A read-only key can never sign, submit or create orders. Those limits are the wallet's USD caps and allowlists plus the key's own IP and recipient lists. With none of them set, treat a leaked read-write key as access to what the wallet holds. The checks every submission passes are listed in how a Vectr wallet guards its key.
Restrictions

Three limits a key can carry

Set when the key is created. Every option narrows what the key can do; none can give it more than the session that created it.

readOnly
true / falseDefaults to false: a key created without it is read-write
allowedIps
up to 50IPv4 addresses or CIDR ranges, checked on every request before the handler runs; empty means any address
allowedRecipients
up to 50Addresses the key's transactions may be sent to, checked by the signer before your wallet rules

The New key button in your profile creates a read-write key with no restrictions. For a read-only key, or to add either list, create it with POST /api-keys from a signed-in session:

curl -X POST https://api.vectr.bot/api-keys \
  -H "Cookie: vectr_session=..." -H "Content-Type: application/json" \
  -d '{"name":"trading-bot","readOnly":false,
       "allowedIps":["203.0.113.10"],
       "allowedRecipients":["0xYourCurve...","0xcaf681a66d020601342297493863e78c959e5cb2"]}'

The response carries the full key once. A key is vectr_ followed by 48 hex characters; the key list only ever shows its first 12 and last 4.

The read-only rule

Six agent tools a read-only key cannot reach

The signing route already refuses a read-only key. These are the remaining ways an agent job could make the backend act for the wallet later, without another request.

// agent/agent.service.ts (trailing comments added here)
const READ_ONLY_BLOCKED_TOOLS = new Set([
  'create_limit_order',   // an order that fills later, from the wallet
  'create_stop_order',
  'create_dca_order',
  'create_twap_order',
  'cancel_order',         // changes what would have filled
  'set_auto_topup',       // lets the backend buy credits from the wallet
]);

// agent/agent.controller.ts: wallet and readOnly come from the key, after the spread
createJob({ ...dto, wallet: req.apiWallet, readOnly: req.apiKeyInfo?.readOnly ?? true });

A read-only job that asks for one of these gets an error back naming the tool, and the model can tell the user to use a read-write key or the Terminal. Every other tool either reads or builds a transaction that comes back unsigned, and the one route that submits transactions refuses the key. If the key information were ever missing, the job would run as read-only: that is the ?? true. What the rule does not cover is the credit an agent turn spends, including an auto top-up you enabled earlier, which is why the checklist below treats auto top-up as a decision.

Revocation

Revoking and rotating a key

Revoke
immediateRevoke in your profile or DELETE /api-keys/:id. Keys are looked up on every request, so the next one fails with 401
Expiry
noneA key works until it is revoked; rotation is up to you
Last used
every requestUpdated on each authenticated request and shown in the key list; a date you cannot explain is a leak
Orders it created
keep runningRevoking a key does not cancel them; cancel them from a signed-in session
Stop everything now
pause switchHalts all signing for the wallet, order fills included, without revoking anything

Rotating a key without downtime, in order:

  1. 01
    Create the new key
    POST /api-keys

    Same restrictions as the old one. Copy it: the full key is shown once.

  2. 02
    Switch the agent
    VECTR_API_KEY

    Deploy the new value and confirm a request succeeds with it.

  3. 03
    Revoke the old key
    DELETE /api-keys/:id

    Its next request fails with 401. Check the last-used date stops moving.

Checklist

Running an agent with a read-write key

Each step bounds what the key can do if it leaks. Together they turn a leak into a capped, visible loss instead of an open one.

  1. 1
    Split the roles
    Give research, dashboards and monitoring a read-only key. Only the one process that submits transactions holds a read-write key.
  2. 2
    Pin the key to your server
    Create it with allowedIps set to your server's IPv4 address or range. A request from anywhere else is refused before any handler runs.
  3. 3
    Pin what it can call
    Set allowedRecipients to the contracts the bot trades: the curves, Uniswap's SwapRouter02 (0xcaf6...5cb2) once a token has graduated, and the factory only if it launches. If you also use the wallet's own recipient allowlist, it applies to every transaction the wallet signs, trades included, so list the same contracts there and let their cooldown pass before the bot starts.
  4. 4
    Cap the wallet
    Set a per-transaction and a 24-hour USD limit sized to the bot's budget. They bind every key on the wallet and every order it creates.
  5. 5
    Fund only the float
    Keep in the Vectr wallet only what the bot needs to trade; hold the rest in a wallet you control.
  6. 6
    Decide on auto top-up
    Any key that runs agent jobs, read-only included, can trigger a credit top-up if it is on. Leave it off for a bot wallet, or set a daily cap you would accept losing.
  7. 7
    Keep the key out of code and prompts
    Load it from an environment variable (VECTR_API_KEY is what the CLI and MCP server read), never from a repository, a prompt or a log line. The model never needs to see it.
  8. 8
    Watch it
    Check the key's last-used date and the wallet's 24-hour spend in your profile, and know where the pause switch is before you need it.
  9. 9
    Rotate, and revoke on doubt
    Rotate on a schedule. If you suspect a leak, pause the wallet first, revoke the key, cancel orders you did not create, then investigate.

For how the agent turns a prompt into a transaction and where the human confirmation sits, read how an AI agent trades on Vectr; the full control set is on the security page and the risks of automated trading in the risk disclosure.

FAQ

API key questions

Should my agent use a read-only or a read-write API key?

Read-only, unless it has to submit transactions or create orders without you. A read-only key can research, read the wallet and build transactions for a person to sign, and a leak costs data and AI credits rather than funds.

What happens to orders a revoked key created?

They keep running. Orders are tied to the wallet, not to the key that asked for them, and fill automatically under the wallet's rules. Cancel them from a signed-in session, or pause the wallet to stop every fill at once.

Can I limit a key to one IP address?

Yes. allowedIps takes up to 50 IPv4 addresses or IPv4 CIDR ranges, and the key is refused from anywhere else. IPv6 addresses are not supported.

Do Vectr API keys expire?

No. A key works until it is revoked, so rotation is up to you. Revoking takes effect on the key's next request.

Can a leaked API key raise my spending limits?

No. Security settings, keys and key export all require a signed-in session. A key can only use the wallet inside the rules that session set.

Can a read-only key cost me money?

Indirectly. It can run agent jobs, which spend your AI credits, and if auto top-up is on, a job that runs short of credits buys more from your Vectr wallet within the daily cap you set. It cannot submit transactions or create orders.

Manage your keysAuthentication referenceWallet security