Authentication

An agent signs in with the wallet it trades from and gets an API key bound to that wallet. There are no passwords and no accounts to create: the wallet's signature is the identity.

Wallet sign-in#

Sign-in follows EIP-4361, Sign-In with Ethereum. It signs a message, never a transaction, and costs no gas.

1. POST /api/v1/auth/challenge with the wallet's address. Orblivion answers with a one-time message that names its own domain, chain 4663, the address, a random nonce and an expiry five minutes away. Its statement says that signing in accepts the Terms of Use.
2. Check the message before signing it. It must name the domain you meant to sign in to, chain 4663 and your own address, and expire soon. The SDKs rebuild the message from its fields and refuse anything else.
3. Sign the message with the wallet (personal_sign, EIP-191) and POST /api/v1/auth/verify with the address and the signature. Orblivion recovers the signer, and if it is the address, answers with an API key.

POST /api/v1/auth/challenge
Content-Type: application/json

{"address": "0xYourAgentWallet"}

{
  "address": "0xyouragentwallet",
  "message": "api.orblivion.com wants you to sign in with your Ethereum account:\n0xYourAgentWallet\n\nSign in to Orblivion to trade through its API. This signs no transaction and costs no gas. By signing in you agree to Orblivion's Terms of Use: https://orblivion.com/docs/terms.html\n\nURI: https://api.orblivion.com\nVersion: 1\nChain ID: 4663\nNonce: ...\nIssued At: ...\nExpiration Time: ...",
  "nonce": "...",
  "domain": "api.orblivion.com",
  "chain_id": 4663,
  "issued_at": 1791168377,
  "expires_at": 1791168677,
  "then": "sign `message` with the wallet (personal_sign, EIP-191) and POST it to /api/v1/auth/verify with the address"
}

POST /api/v1/auth/verify
Content-Type: application/json

{"address": "0xYourAgentWallet", "signature": "0x<65 bytes>", "nonce": "<optional: the challenge's nonce>"}

{
  "api_key": "pit_w_...",
  "key_id": 12,
  "wallet": "0xyouragentwallet",
  "account": {"id": 3, "name": "w-0xyouragentwallet"},
  "expires_at": 1793760377,
  "orbio_agent": {"agent_id": 282, "token": "0x...", "symbol": "...", "role": "agentWallet", "name": "..."},
  "orbio_check": "ok",
  "note": "shown once; Orblivion stores only its SHA-256. Live endpoints accept only this wallet."
}

• A challenge works once, for five minutes. A wallet may have up to five open challenges; verify tries the newest first, or exactly the one whose nonce you send.
• orbio_agent says whether the wallet is an Orbio agent's agentWallet or owner, from Orbio's public agent list, or null. A server may be set to sign in only Orbio agents and owners; any other wallet then gets 403 NOT_ORBIO_AGENT.
• The message's domain is the server's configured domain, never the Host header you sent, so a sign-in message for another site can't be replayed here.

API keys#

Send the key on every request that needs one:

Authorization: Bearer pit_w_...

Keep the key secret. A stolen key acts as that wallet at Orblivion until it expires or is revoked: it can plan trades, pause or stop that wallet's hosted agents and turn their live switch on within sessions the owner already signed. It can't move funds by itself: every trade still needs the wallet's own signature, or a session the main key signed, and no key can widen a session's limits.

What a key can act for#

A key acts only for its own wallet:

• prepare, build, revoke, a new session grant, and simulate with a wallet refuse any other wallet with 403 WALLET_MISMATCH.
• submit relays only a transaction signed by the key's wallet, or by the executor of one of that wallet's sessions.
• A session's trades are open to its wallet's key and its executor's key; its grant and revoke only to the wallet's.
• Hosted agents belong to the wallet whose key created them. Another wallet's key gets 403 FORBIDDEN.

Check a key#

GET /api/v1/auth/me answers the key's wallet, account, key_id, expires_at and orbio_agent.

See your account#

A key bound to a wallet reads that wallet's own account: its trades through Orblivion (GET /api/v1/me/trades), its balances at independent prices with its fee tier (GET /api/v1/me/portfolio), and its active sessions and hosted agents (GET /api/v1/me/sessions). Never another wallet's. In the SDKs: client.me.trades(), client.me.portfolio(), client.me.sessions(). In a browser, /account.html signs in with the wallet and shows the same. See the API reference.

Revoke a key#

POST /api/v1/auth/revoke with the key itself revokes it at once:

curl -s -X POST https://api.orblivion.com/api/v1/auth/revoke -H "Authorization: Bearer $ORBLIVION_API_KEY"

{"revoked": true, "key_id": 12, "wallet": "0xyouragentwallet"}

Every later request with it gets 401 UNAUTHORIZED.

Revoke every key, without one#

If you lost a key, or think one leaked, the wallet itself can revoke every key bound to it: ask for a challenge with "purpose": "revoke-all", sign it, and send it to POST /api/v1/auth/revoke-all (API reference). A revoke challenge can't sign in, and a sign-in challenge can't revoke. Sessions are separate: revoke those too if the key could reach them (Sessions). A key can't widen a session, and revoking a session stops it for every key at once.

Browsers#

An agent sends no cookies, so the rules below never affect it. They protect people using a browser:

• A POST that carries an Origin header must come from the API's own origin; otherwise 403 CSRF_REFUSED.
• A POST that carries cookies must be JSON and carry the header X-Pit-Client, which a page on another site can't send without a preflight that Orblivion never approves.

Rate limits on sign-in#

Challenges and verifies are limited per client address (a burst of 10, then one every 10 seconds) and overall. Failed authentications (an unknown, expired or revoked key) are limited separately, per client address; past the limit the answer is 429 RATE_LIMITED with a Retry-After header. See Rate limits.