API keys

An API key lets code call the AGENTEX buyer API for your account. This page covers creating keys, what each scope allows, how a key is bound to one payment asset, its spend limit, expiry and rate limit, revocation, and what a key can never do. It is for anyone who automates research purchases.

Create a key#

Keys are created only on the website, signed in with the wallet whose balance the key will spend.

1. Open Developers and sign in with your wallet.
2. Select Create API key.
3. Fill in the form:
   • Name: a label for you, up to 100 characters.
   • Environment: the payment asset the key pays in. A Solana account offers SOL and USDC; an EVM account offers ETH on Robinhood Chain.
   • Scopes: what the key may call (see below). catalog:read, quotes:write, runs:read and billing:read are selected by default.
   • Spend limit: the most the key may ever commit, in the key's currency.
   • Expires in (days): 1 to 90. The default is 30.
   • Requests / minute: 1 to 600. The default is 60.
   • Allowed listing IDs (optional): leave empty for all listings, or enter up to 50 listing IDs to restrict the key.
4. Select Create key.
5. Under Copy your new key now, select Copy, store the secret, then select I saved this key.

The secret looks like agx_live_ followed by 43 characters. AGENTEX stores only a hash of it and shows it once: "Copy this secret now. AGENTEX stores only its hash and cannot show it again." If you lose it, revoke the key and create a new one. The keys table afterwards shows only the key prefix and its last four characters.

A key's grant (scopes, asset, limits, expiry and listing restriction) cannot be changed after creation. To change it, create a new key and revoke the old one.

Scopes#

Give each key only the scopes its job needs. A key without the scope for a route gets 403 with "This API key does not have the scope required for this route." Every route not listed here refuses any API key with 401 and "API keys are not accepted for this route."

Monitor scopes are offered only to EVM accounts, because monitors watch EVM chains and are paid in ETH. In production an API key cannot create a monitor: monitors are prepaid, and prepaid monitors need a signed-in session. See Webhooks.

One key, one asset#

Every key pays in exactly one asset, fixed by its Environment:

• A Solana account creates SOL or USDC keys; an EVM account creates ETH keys. Trying the other way is refused.
• A SOL or USDC key uses the /v1/solana-custody/... routes and always quotes in its own asset. Naming the other asset returns 403 with "This API key is restricted to a different payment environment."
• An ETH key uses the /v1/custody/... routes. Calling a route of the other rail returns the same 403.
• A key sees only paid runs bought in its own asset. Anything else, including your creator test runs and runs paid in another asset, is 404 "This run was not found."
• To pay in two currencies, create two keys.

Spend limit#

spendLimitAtomic is a lifetime budget for the key, in its asset's atomic units (lamports, micro-USDC or wei). It is not a rate and it does not reset.

Each quote accepted through the key counts once:

• while the run is reserved or its billing is pending: the full reservation (the quote's maximumBuyerDebitAtomic);
• once settled: only the amount actually charged, so a refunded failure or an early cancellation frees the rest;
• while an acceptance request is in flight: the quote maximum.

An acceptance is refused with 403 "Accepting this quote would exceed the API key spend limit." unless the key's committed spend plus the new quote's maximum fits within the limit. Acceptances made on the website, or through another key, do not count against this key. Your AGENTEX balance must also cover the reservation; see Charges and reservations.

Expiry, rate limits and listing restrictions#

The limits for runs themselves (3 active runs and 20 runs in 24 hours per account) are on Quotes and runs.

Check a key from code#

Any valid key can read its own grant. Use it to check the key's asset and remaining budget before asking a person to approve a quote.

curl -s -H "Authorization: Bearer $AGENTEX_API_KEY" https://agentex.sh/v1/buyer/key

{
  "key": {
    "name": "quickstart",
    "prefix": "agx_live_Ab3x",
    "last4": "9QzT",
    "scopes": ["catalog:read", "quotes:write", "runs:read", "billing:read"],
    "profile": "solana_sol",
    "assetId": "solana:mainnet-beta/native",
    "listingIds": null,
    "spendLimitAtomic": "50000000",
    "spendUsedAtomic": "1451000",
    "remainingSpendAtomic": "48549000",
    "rateLimitPerMinute": 60,
    "requestsLast24h": 12,
    "expiresAt": "2026-10-28T09:00:00.000Z",
    "status": "active"
  }
}

In the SDK this is agentex.key(); in the CLI, npx agentex-buyer key. The Usage tab on Developers shows the same numbers for every key: requests in the last 24 hours, rate limit, spend against the limit, allowed listings, expiry and last use.

Revoke a key#

1. On Developers, in API keys, open the key's actions menu and select Revoke.
2. Confirm with Revoke key.

Revocation is immediate and permanent: every later request with that key gets 401 "A valid, active API key is required." Runs the key already accepted continue and settle normally. Revoking a key twice changes nothing.

To rotate a key: create the new key, deploy it, confirm it works with GET /v1/buyer/key, then revoke the old one.

Store keys safely#

• Keep the secret in a secret manager or the AGENTEX_API_KEY environment variable. Never commit it or paste it into issue trackers, logs or chat.
• Use keys from servers, scripts and command lines, not from web pages or mobile apps that ship code to users.
• Send the key only in the Authorization: Bearer header, only over HTTPS. The SDK refuses plain HTTP to any non-local host and never includes the key in error messages.
• Use one key per program or environment, with the smallest spend limit and the fewest scopes that work, so you can revoke one without affecting the others.
• Leave out runs:cancel unless the program needs it, and restrict the key to specific listings when it only ever buys from them.
• If a key may have leaked, revoke it first and investigate afterwards.

Each authenticated request records its route, method, time and response status for the usage view. Request bodies, headers and parameter values are never recorded.

What a key can never do#

• Create, list or revoke API keys.
• Deposit, withdraw or move funds in any way. Deposits and withdrawals need your wallet's own signature on the Wallet page.
• Accept a quote without that quote's exact contract hash, or spend beyond its spend limit, its asset or its allowed listings.
• Pay in any asset other than its own.
• Create monitors or delivery destinations, or change a monitor other than stopping it.
• Create share links or download CSV, Markdown or HTML exports.
• Read runs of other accounts, your creator test runs, or runs paid in another asset.
• Use Studio, publish, list or price agents.
• Be combined with a signed-in session: a request carrying both a session cookie and a key is refused with 400 "Send either a session cookie or an API key, not both."

See also API keys and signing for how keys relate to wallet signatures.