GET /whoami

Get the authenticated principal

Get the authenticated principal.

operationId: fetchWhoami

Declared server: https://api.testnet.nexus.xyz/v1. See Networks.

Not reachable through CCXT. Credential introspection. The nearest unified method, fetchAccounts, lists sub-accounts, and a Nexus credential maps to exactly one account (see api/ccxt-surface.md).

Authentication: agentAuth, hmacAuth.

Get the authenticated principal

get

/whoami

Returns who the request authenticated as: the account the credential acts for, the credential's key id, the caller's rate limit tier, and whether the credential is a delegated agent key. For an agent key, account is the wallet that registered the agent, not the agent's own address. Answered from the verified credential alone, with no call to the matching engine, so it keeps answering when account reads that the engine serves (such as GET /account) cannot. This endpoint does not consume a rate limit token, so a client can call it freely, for example once at startup to learn which account its API key belongs to.

Authorizations

X-API-KeystringRequired

HMAC API key authentication. Send three headers:

• X-API-Key: your key ID (e.g. nx_a1b2c3...)
• X-Timestamp: current time in unix milliseconds
• X-Signature: hex(hmac_sha256(secret, timestamp + "\n" + METHOD + "\n" + path + "\n" + query + "\n" + sha256_hex(body)))

Timestamp must be within 30 seconds of server time.

The key is network-scoped; the signature is not. The canonical string above has no network component, so the same signed request is byte-identical on every host. What stops a testnet key from authenticating against mainnet is that the key does not exist in that host's key store — sign only for the host that minted the key, and never replay a signed payload against another network. Presented to the wrong host, a key is refused with the same opaque 401 as an unknown key and must not be retried there. See “API keys are bound to one network” in the API description.

Responses

200

The authenticated principal.

application/json

The principal a request authenticated as, as served by GET /whoami. Every field is read from the verified credential.

accountstringRequired

The account the credential acts for, as 0x + 40 lowercase hex characters. For an agent key this is the delegating wallet, not the agent's address.

Example: 0x742d35cc6634c0532925a3b844bc9e7595f0beb0Pattern: ^0x[0-9a-f]{40}$

key_idstring · nullableRequired

The credential's key id. For an HMAC API key (hmacAuth) it is the X-API-Key value; for an agent key (agentAuth) it is agent: followed by the agent's 0x address. Null for a session token, which carries no key.

Example: nx_a1b2c3d4e5f6

tierstring · enumRequired

The caller's rate limit tier, spelled as GET /account/rate-limit reports it.

Possible values:

is_agentbooleanRequired

True when a delegated agent key (agentAuth) signed the request. An agent key can trade but can never withdraw.

401

Authentication failed. All 401 responses return the same opaque body to prevent information leakage. A credential minted on a different network is one of the causes it hides — by design, so that a key id cannot be probed for existence on another network. Do not retry it against another host.

application/json

get/whoami

GET /v1/whoami HTTP/1.1
Host: api.testnet.nexus.xyz
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "account": "0x742d35cc6634c0532925a3b844bc9e7595f0beb0",
  "key_id": "nx_a1b2c3d4e5f6",
  "tier": "pro",
  "is_agent": false
}

Test it cannot sign this request. X-Signature is an HMAC computed per call: see Authentication, or use an SDK.

---

_{API version 0.9.122}