> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xmonaco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# V0.8.4

# 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

1. **Owner** calls `upsertDelegatedAgent` to register an agent address and define its constraints.
2. **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.
3. **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

```typescript theme={null}
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:

```typescript theme={null}
// 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:

```typescript theme={null}
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

```typescript theme={null}
// 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.

```typescript theme={null}
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

```bash theme={null}
npm install @0xmonaco/core@0.8.4 @0xmonaco/types@0.8.4 @0xmonaco/react@0.8.4
# or bun
bun add @0xmonaco/core@0.8.4 @0xmonaco/types@0.8.4 @0xmonaco/react@0.8.4
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.