Monaco Protocol SDK v0.8.4

Delegated Agents

Delegated agents let an owner wallet authorize a separate signer address to submit orders on the owner’s behalf. The owner retains custody of all funds, collateral movement, and withdrawal rights. The agent can only perform the trading actions permitted by its policy.

How it works

Owner calls upsertDelegatedAgent to register an agent address and define its constraints.
Agent authenticates with its own wallet (normal sdk.auth challenge flow), then calls createDelegatedSession with the owner’s user ID to receive a short-lived, owner-scoped delegated auth session.
Agent signs trading requests with that delegated session. Orders are matched and settled against the owner’s margin accounts; the agent wallet is recorded as the signer.

Owner setup

const agent = await sdk.delegatedAgents.upsertDelegatedAgent({
  agentAddress: "0xYourAgentWalletAddress",
  allowedActions: ["CREATE_ORDER", "CANCEL_ORDER", "REPLACE_ORDER"],
  allowedTradingPairIds: [btcPerpTradingPairId],
  allowedOrderTypes: ["LIMIT"],
  allowedTimeInForce: ["GTC", "IOC"],
  maxLeverage: "10",
  maxOrderNotional: "100000",
  expiresAt: "2026-12-31T23:59:59Z",
});

console.log(agent.id); // UUID — store for revocation

Agent session

The agent first authenticates with its own wallet, then exchanges for an owner-scoped delegated session using a locally generated session public key:

// Agent is already authenticated with its own wallet address
const session = await sdk.delegatedAgents.createDelegatedSession({
  ownerUserId: ownerUserId,
  sessionPublicKey,
});

// From here, signed delegated requests act on the owner's account
// while preserving the agent address for policy checks and audit.

Placing orders as an agent

Once the delegated session is active, place orders normally. Pass strategyKey to let Monaco auto-resolve or create an isolated margin bucket for that key, so you never need to manage marginAccountId directly:

await sdk.trading.placeLimitOrder(btcPerpTradingPairId, "BUY", "0.5", "65000", {
  tradingMode: "MARGIN",
  positionSide: "LONG",
  leverage: "5",
  strategyKey: "btc-mm-strategy-a",
});

Each unique strategyKey maps to a dedicated, owner-owned margin account. Omitting strategyKey uses the owner’s default margin account for the trading pair.

List and revoke

// List all active delegated agents for the authenticated owner
const { agents } = await sdk.delegatedAgents.listDelegatedAgents();

// Revoke a specific agent
const result = await sdk.delegatedAgents.revokeDelegatedAgent(agent.id);
// result.status === "REVOKED"

Revoking an agent blocks future policy-gated trading for that agent. Existing delegated auth sessions may still authenticate until session expiry, but create, cancel, replace, and close actions fail because Monaco re-checks the active delegation before each mutation. In-flight orders already submitted are unaffected.

`UpsertDelegatedAgentRequest` shape

Field	Type	Required	Description
`agentAddress`	string	yes	EVM wallet address of the agent
`allowedActions`	`DelegatedAgentAction[]`	yes	`"CREATE_ORDER"`, `"CANCEL_ORDER"`, `"REPLACE_ORDER"`
`allowedTradingPairIds`	string[]	no	Restrict to specific trading pair UUIDs; omit to allow all
`allowedOrderTypes`	string[]	no	e.g. `["LIMIT"]`; omit to allow all
`allowedTimeInForce`	string[]	no	e.g. `["GTC", "IOC"]`; omit to allow all
`maxLeverage`	string	no	Maximum leverage the agent may request, e.g. `"10"`
`maxOrderNotional`	string	no	Maximum notional per order in quote asset units
`expiresAt`	string	no	ISO 8601 expiry — agent policy auto-expires at this time

`strategyKey` on order placement

Both placeLimitOrder and placeMarketOrder now accept an optional strategyKey field. Monaco uses this to resolve the owner’s parent margin account and target the isolated bucket for the given (market, strategyKey) pair. This is the recommended way for delegated agents to trade without managing bucket IDs manually — but it is also usable in non-delegated flows for strategy tagging and segregated margin accounting.

await sdk.trading.placeLimitOrder(tradingPairId, "SELL", "1.0", "3000", {
  tradingMode: "MARGIN",
  positionSide: "SHORT",
  leverage: "3",
  strategyKey: "eth-trend-follow",
});

strategyKey is also available on batchCreate and batchReplace per-order params.

Migration

No breaking changes. All additions are opt-in:

sdk.delegatedAgents is a new module — existing code is unaffected.
strategyKey is optional — all existing order placement calls work without change.

Upgrade

npm install @0xmonaco/[email protected] @0xmonaco/[email protected] @0xmonaco/[email protected]
# or bun
bun add @0xmonaco/[email protected] @0xmonaco/[email protected] @0xmonaco/[email protected]

Learn

Build

Libraries

APIs

Resources

V0.8.4

Monaco Protocol SDK v0.8.4

Delegated Agents

How it works

Owner setup

Agent session

Placing orders as an agent

List and revoke

`UpsertDelegatedAgentRequest` shape

`strategyKey` on order placement

Migration

Upgrade

​Monaco Protocol SDK v0.8.4

​Delegated Agents

​How it works

​Owner setup

​Agent session

​Placing orders as an agent

​List and revoke

​UpsertDelegatedAgentRequest shape

​strategyKey on order placement

​Migration

​Upgrade

Monaco Protocol SDK v0.8.4

Delegated Agents

How it works

Owner setup

Agent session

Placing orders as an agent

List and revoke

`UpsertDelegatedAgentRequest` shape

`strategyKey` on order placement

Migration

Upgrade