`approveAgent`

Authorizes an agent wallet to sign actions on behalf of the signing account. Most Exchange API actions — order, cancel, modify2, the margin actions — are agent-signed, so approving an agent is the prerequisite for programmatic trading: the agent key signs day to day, while the account's own key stays offline except for this approval and the direct EIP-712 actions.

The same action also revokes an agent — see Revoking an agent.

POST/exchangetype approveAgent

Authorize (or revoke) the agent key that signs day-to-day trading. Do this once before trading.Direct EIP-712, signed by the account key

Action fields

agentAddressstring · addressrequired

Agent wallet to authorize. The zero address revokes instead.

apiVersioninteger · uint32required

TxFlow signing API version.

chainIdinteger · uint32required

TxFlow chain ID.

nonceinteger · uint64required

Fresh millisecond timestamp. Direct EIP-712 actions carry the nonce inside the action as well as in the outer payload; the two must match.

txflowNetworkstringrequired

TxFlow network name used by the EIP-712 action and domain.

typestringrequired

Must be `approveAgent`.

"approveAgent"

agentNamestringnullableoptional

Label for this agent, at most 64 characters. Omitted or `null` is treated as the empty label.

Request example

curl -X POST https://rpc.txflow-testnet.xyz/exchange \
  -H "Content-Type: application/json" \
  -H "x-api-version: 2026-08-16" \
  -d '{
  "action": {
    "type": "approveAgent",
    "txflowNetwork": "TxFlow-Testnet",
    "chainId": 2511,
    "apiVersion": 1,
    "agentAddress": "0x0202020202020202020202020202020202020202",
    "agentName": "my-trading-bot",
    "nonce": 1757992743994
  },
  "signature": {
    "r": "0x<r>",
    "s": "0x<s>",
    "v": 27
  },
  "nonce": 1757992743994,
  "vaultAddress": null,
  "signatureChainId": null
}'

Try it

testnet · no account yet

Generates a throwaway key in your browser, claims testnet USDC and authorizes an agent key. The account is kept while you browse the docs and lost on reload.

Response · ApproveAgent 200

codeinteger

`0` on success.

dataobject

typestring

The action's internal name, which does not always match the request `type`.

"ApproveAgent"

statusstring

A rejected request returns `err` with a non-zero `code` and the reason in `message` (or `response`).

"ok"

Response example

{
  "status": "ok",
  "code": 0,
  "data": {
    "type": "ApproveAgent",
    "data": {
      "statuses": [
        "success"
      ]
    }
  }
}

txflowNetwork, chainId, and apiVersion must match the node's configuration, otherwise the request is rejected with Network mismatch: expected <x>, got <y> (likewise Chain ID mismatch and API version mismatch).

Agents are keyed by label

An account holds a map of agentName → agentAddress. The label, not the address, is the key:

Approving a new label adds an agent. An account may hold at most 100 labels; beyond that the request fails with Max agents per account reached (100).
Approving an existing label rebinds it to the new address and drops the old one, which is how you rotate an agent key. This does not consume another slot.
Omitting agentName uses the empty label — a single unnamed agent per account. Sending a second unnamed approval replaces the first rather than adding one.

An agent address may only be bound to one account. Reusing an address already registered as another account's agent fails with Agent address is already used, and approving your own address fails with Cannot approve self as agent.

Revoking an agent

Set agentAddress to the zero address and name the label to revoke:

{
  "type": "approveAgent",
  "txflowNetwork": "TxFlow-Testnet",
  "chainId": 2511,
  "apiVersion": 1,
  "agentAddress": "0x0000000000000000000000000000000000000000",
  "agentName": "my-trading-bot",
  "nonce": 1757992743994
}

The label must already exist, otherwise the request fails with Agent with this label does not exist. Revocation removes the label and frees the address for reuse.

Preconditions

Error	Cause
`Please deposit first`	The signing address has no account yet — deposit before approving an agent
`Cannot approve self as agent`	`agentAddress` equals the signing address
`Agent address is already used`	That address is already an agent of some account
`Agent with this label does not exist`	Revoking (zero address) a label the account does not hold
`Max agents per account reached (100)`	Adding a new label at the 100-label limit
`Agent name length exceeds maximum of 64 characters`	`agentName` is too long

On a multi-sig account this action must arrive wrapped in a multiSig payload — an agent cannot approve further agents, and the converted account's original key can no longer single-sign.

Signing

This is a direct EIP-712 user-signed action, signed by the account key rather than an agent. Its exact primary type is:

ApproveAgent(string txflowNetwork,uint32 chainId,uint32 apiVersion,address agentAddress,string agentName,uint64 nonce)

When agentName is null or omitted, hash the empty string "" in its place. If the outer signatureChainId is set, use it as the EIP-712 domain chain ID; the action's chainId field does not change. See Signing.

Next steps

Once included in a block, the agent may sign on the account's behalf. List an account's agents with approvedAgents, and resolve which account an agent belongs to with agentOwner.