Agent Keys

Agent key registration and management. Three operations.

An agent is an Ethereum-derived keypair that can sign trading requests on your behalf without exposing your main wallet. You register the agent's address once, authorized by a signature from the owning wallet, and from then on the agent key carries the trading authority — while the wallet key stays offline.

No session token is required for any operation in this section. Registration is authorized in-band by an EIP-712 signature in the request body, so it needs no credential at all. The two management operations (GET /agents, DELETE /agents/{address}) authenticate with your HMAC API key.

Operation

Authorization

POST /agents/register

EIP-712 signature in the request body. No session token, no API key.

GET /agents

hmacAuth

DELETE /agents/{address}

hmacAuth

Base URL for every example below: https://exchange.nexus.xyz/api/exchange.

The EIP-712 payload

Registration is authorized by a typed-data signature from the wallet that will own the agent.

Domain

{
  "name": "Nexus Exchange",
  "version": "1",
  "chainId": "<testnet chain id>"
}

Type

RegisterAgent {
  address agent
  uint64  expiresAt
  uint64  nonce
}

Notes on getting this right:

The signature covers three fields — agent, expiresAt, nonce. The owning wallet is not part of the typed data; it is sent alongside in the request body and the server checks that the recovered signer matches it.
The typed-data field names are camelCase (expiresAt), while the JSON request body uses snake_case (expires_at). Sign the camelCase names; send the snake_case ones.
If you let expires_at default server-side, you have nothing to sign. Compute the expiry yourself, sign it, and send it explicitly.
The contract writes the domain's chainId as the placeholder <testnet chain id> and does not pin a value. Published Nexus chain IDs are listed under Developer Environment Setup; confirm the value your target gateway expects before signing, since a domain mismatch produces signer_mismatch, not a descriptive error.

`POST /agents/register`

Register a new agent key for your wallet. An agent is an Ethereum-derived keypair that can sign trading requests on your behalf without exposing your main wallet. The registration is authorized by an EIP-712 signature from the wallet that will own the agent — no session token required.

EIP-712 domain: { name: 'Nexus Exchange', version: '1', chainId: <testnet chain id> }. Typed data type: RegisterAgent { address agent, uint64 expiresAt, uint64 nonce }.

Authentication: None — the request authorizes itself with the EIP-712 signature it carries.

Request body

AgentRegistrationRequest — application/json, required.

Field

Type

Required

Description

wallet

string

Yes

Owner wallet address (0x-prefixed, 20 bytes)

agent

string

Yes

Agent Ethereum address (0x-prefixed, 20 bytes) derived from the agent keypair

expires_at

integer (int64)

Expiry as Unix ms. Optional — defaults to now+30 d. Must be in [now+1d, now+90d].

nonce

integer (int64)

Yes

Monotonic nonce. Use the current Unix timestamp in ms as a safe starting value.

signature

string

Yes

EIP-712 signature over RegisterAgent{agent, expiresAt, nonce} from the wallet private key (0x-prefixed)

label

string

Optional human-readable label for the agent (e.g. my-bot)

Responses

`200`

Agent registered. The contract gives this response an example but no named schema.

Field

Type

Description

agent_address

string

The registered agent address (0x-prefixed)

expires_at

integer (int64)

Effective expiry, Unix ms — the value you sent, or the server default if you omitted it

`400`

Bad request: bad_wallet, bad_agent, expiry_out_of_range ([1 d, 90 d] from now), or invalid_json.

`401`

signature_invalid or signer_mismatch — the EIP-712 signature did not recover to the claimed wallet.

`409`

duplicate_agent — the agent address is already registered to this wallet.

Example

curl -X POST 'https://exchange.nexus.xyz/api/exchange/agents/register' \
  -H 'Content-Type: application/json' \
  -d '{
    "wallet": "0xAbCdEf0123456789AbCdEf0123456789AbCdEf01",
    "agent": "0x1234567890AbCdEf1234567890AbCdEf12345678",
    "expires_at": 1782000000000,
    "nonce": 1,
    "signature": "0xdeadbeef..."
  }'

Response:

{
  "agent_address": "0x1234567890AbCdEf1234567890AbCdEf12345678",
  "expires_at": 1782000000000
}

`GET /agents`

List your agents.

Returns all non-expired agent keys registered to the authenticated wallet. Expired agents are filtered out server-side, so an agent disappearing from this list is the expected end of its lifecycle, not an error.

Authentication: hmacAuth — HMAC API key.

Responses

`200`

Array of agent records. Items are AgentInfo.

Field

Type

Description

address

string

Agent address (0x-prefixed)

expiresAt

integer (int64)

Expiry, Unix ms

registeredAt

integer (int64)

Registration time, Unix ms

label

string | null

Optional label

Response field names are camelCase here, unlike the snake_case registration request body.

`401`

HMAC authentication required.

Example

curl 'https://exchange.nexus.xyz/api/exchange/agents' \
  -H "X-API-Key: nx_a1b2c3d4e5f67890" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE"

Response:

[
  {
    "address": "0x1234567890AbCdEf1234567890AbCdEf12345678",
    "expiresAt": 1782000000000,
    "registeredAt": 1779000000000,
    "label": "my-bot"
  }
]

See Authentication for how to build X-Timestamp and X-Signature.

`DELETE /agents/{address}`

Revoke an agent.

Immediately revoke an agent key. Any in-flight requests signed by the revoked agent will be rejected after this call returns.

Authentication: hmacAuth — HMAC API key.

Parameters

Name

Type

Required

Description

address

path

string

Yes

Agent address to revoke (0x-prefixed)

Responses

`200`

Agent revoked.

`401`

HMAC authentication required.

`404`

Agent not found or not owned by you. Ownership failures are reported as 404, not 403 — you cannot probe for other wallets' agents.

Example

curl -X DELETE 'https://exchange.nexus.xyz/api/exchange/agents/0x1234567890AbCdEf1234567890AbCdEf12345678' \
  -H "X-API-Key: nx_a1b2c3d4e5f67890" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE"

Operating notes

Expiry is bounded. An agent must expire between 1 and 90 days from registration; omitting expires_at gives you 30 days. There is no renewal operation in version 0.9.27 — re-register a fresh agent before the old one lapses.
Nonces are monotonic per wallet. Using the current Unix millisecond timestamp as the nonce satisfies that ordering without tracking state.
Revocation is immediate, and it applies to in-flight requests: a request signed by a revoked agent is rejected once the DELETE returns.
Registration is unauthenticated at the transport layer. Anyone can submit a registration; only a valid EIP-712 signature from the claimed wallet is accepted. Guard the wallet key accordingly — a signature over RegisterAgent grants trading authority for up to 90 days.

Status: testnet preview. Agent registrations are not yet durable across gateway restarts — treat them as re-creatable alongside API keys.

PreviousAuthentication

NextRate Limits

Last updated 2 days ago