For Agents - Edel Developer Docs

Install the public Edel backend skill in your agent client:

npx skills add Edel-Finance/edel-ai-config --skill edel-backend

Skill installation does not create an account or complete authentication. It provides instructions, not credentials, signing authority, or permission to move money.

Start here

Read the authentication and secure setup tutorial and check current capabilities.
Confirm the owner’s existing identity and the owner-approved scope. Do not create a replacement account.
Stop for the human at each browser passkey step. Connect with an API key through the owner’s browser approval, below; never ask for a passkey, a session bearer or a DFNS credential, and never approve yourself.
Begin with read-only checks. Before trading, require an active Canton Party binding and separate explicit owner approval for the exact action. Installation and a key grant neither.

Connect with an API key

The venue gives an agent an API key through a one-time browser approval (the RFC 8628 device grant).

POST /v1/agent-connect/start with clientName and scopes (read, or read and trade). The answer carries connectCode, userCode, verificationUrl, expiresInSeconds (600) and intervalSeconds (5).
Show the owner verificationUrl and userCode. The owner opens the page, signs in with a passkey, checks that the code matches and approves.
POST /v1/agent-connect/complete with connectCode every intervalSeconds. It answers authorization_pending until the owner approves, slow_down when you ask faster (add five seconds to your interval), expired after ten minutes or once the key was collected, and approved with apiKey exactly once. Start polling right after step 1: the owner may approve before you show the code again.
Send Authorization: Bearer <apiKey> on account and order routes. Store the key in a file only you can read; never put it in command-line arguments, logs or chat.

The handshake ends within ten minutes and is not a live data feed, so it uses REST. Live prices, trades and account updates still come over WebSockets.

Use the Edel MCP server

Testnet target: https://mcp-testnet.edel-api.xyz/mcp. This is a separately deployed, stateless Streamable HTTP service. The endpoint must be provisioned and verified by this venue’s rollout; source configuration alone is not evidence that it is live.

Direct remote client (preferred)

Obtain an expiring key with the device-grant flow above. For the local convenience command, run bun run --cwd apps/mcp connect, open the printed verification URL and approve its code in the browser. The command saves the approved key only in the client file ~/.edel/mcp-key.json (mode 0600).
Configure your remote MCP client with the URL and an Authorization: Bearer <apiKey> header on every request. Load the value from your private client file or secret store; never put a real key in chat, a command-line argument, source control or logs. Configuration syntax varies by client:

{
  "mcpServers": {
    "edel": {
      "url": "https://mcp-testnet.edel-api.xyz/mcp",
      "headers": { "Authorization": "Bearer <client-held-api-key>" }
    }
  }
}

Call edel_connect with the approved scopes to confirm the current key metadata, then edel_status for account readiness. edel_markets and edel_price read snapshots; live updates use WebSockets.
An expired or revoked key is refused by the same trader auth middleware as REST. Run the local connect command again and update the remote header. No MCP session id grants access.

The hosted server never writes a key to disk and never keeps a key between requests. Its edel_connect only confirms the supplied key; it does not start a browser grant or save a key on Railway.

Optional local bridge

An MCP client that starts stdio processes may run bun run --cwd apps/mcp start with MCP_PUBLIC_URL set to the remote MCP URL. The local edel_connect tool runs browser approval and saves the client key; other tools forward over HTTP with that key. Without MCP_PUBLIC_URL, the local tools call REST directly. Direct remote clients do not require this bridge. The local edel_connect rechecks stored credentials with the API and consumes settled grants before answering; reconnect: true forces fresh approval.

Tools and their REST operations

The MCP stays at parity with the public REST API, deposits and withdrawals excepted (owner rule, 2026-09-19). Every public operation is called by a tool with the same request fields and error codes, or excluded for one of the closed reasons below; a test fails the build when either drifts. The server fills accountId from the approved key; every other request field is a tool input with its REST name.

Tool	REST operations
`edel_connect`	`POST /v1/agent-connect/start`, `POST /v1/agent-connect/complete`, `GET /v1/api-keys/current`
`edel_status`	`GET /v1/accounts/:accountId`, `GET /v1/accounts/:accountId/party`
`edel_markets`	`GET /v1/markets`
`edel_price`	`GET /v1/markets/:marketId/stats`, `GET /v1/markets/:marketId/book`
`edel_place_order`	`POST /v1/orders`
`edel_cancel_order`	`POST /v1/orders/:orderId/cancel`
`edel_orders`	`GET /v1/accounts/:accountId/orders/open`
`edel_positions`	`GET /v1/accounts/:accountId/positions`
`edel_close_position`	`GET /v1/accounts/:accountId/positions`, `POST /v1/orders`
`edel_order_history`	`GET /v1/accounts/:accountId/orders`
`edel_trade_history`	`GET /v1/accounts/:accountId/fills`
`edel_position_history`	`GET /v1/accounts/:accountId/positions/history`
`edel_funding`	`GET /v1/accounts/:accountId/positions/history`
`edel_account`	`GET /v1/accounts/:accountId`
`edel_kyc_status`	`GET /v1/accounts/:accountId/kyc`
`edel_market`	`GET /v1/markets/:marketId`
`edel_candles`	`GET /v1/markets/:marketId/candles`
`edel_candidate_markets`	`GET /v1/market-data/candidate-markets`
`edel_leaderboard`	`GET /v1/leaderboard`
`edel_affiliate_availability`	`GET /v1/affiliate/availability`
`edel_preview_order`	`POST /v1/orders/preview`
`edel_place_order_batch`	`POST /v1/orders/batch`
`edel_order`	`GET /v1/orders/:orderId`
`edel_cancel_order_batch`	`POST /v1/orders/batch/cancel`

Excluded because	Operations
Deposits and withdrawals stay with the owner in the browser (owner decision, 2026-09-19).	`POST /v1/withdrawals`, `GET /v1/withdrawals/:withdrawalId`, `POST /v1/withdrawals/:withdrawalId/authorize`, `POST /v1/withdrawals/:withdrawalId/confirm`, `POST /v1/accounts/:accountId/deposits`, `POST /v1/accounts/:accountId/deposits/confirm`
The flow needs the owner’s passkey, social sign-in or local signing ceremony in a browser, which an agent cannot perform.	`GET /v1/auth/capabilities`, `POST /v1/auth/social/register`, `POST /v1/auth/social/register/recover`, `POST /v1/auth/register/complete`, `POST /v1/auth/login/init`, `POST /v1/auth/login/complete`, `POST /v1/auth/social/login`, `POST /v1/auth/mapping/recover`, `POST /v1/accounts/:accountId/party/consent`, `POST /v1/accounts/:accountId/party`, `POST /v1/accounts/:accountId/party/complete`, `POST /v1/accounts/:accountId/local-signing-wallet`, `GET /v1/accounts/:accountId/local-signing-funding-intents`, `POST /v1/accounts/:accountId/agent-connect/approve`
The API refuses every API key on this route with 403 passkey_required; widening the key allowlist is an owner security decision.	`GET /v1/accounts/:accountId/transfers`, `GET /v1/accounts/:accountId/affiliate/earnings`, `GET /v1/accounts/:accountId/affiliate/profile`, `POST /v1/accounts/:accountId/affiliate/registration`, `POST /v1/accounts/:accountId/kyc/skip`, `POST /v1/accounts/:accountId/faucet-grant`, `PUT /v1/accounts/:accountId/favorites/:marketId`, `DELETE /v1/accounts/:accountId/favorites/:marketId`, `GET /v1/accounts/:accountId/api-keys`, `DELETE /v1/accounts/:accountId/api-keys/:keyId`
The route mints or manages a WebSocket ticket, a credential the MCP request and response transport cannot use.	`POST /v1/realtime/ticket`, `PUT /v1/realtime/ticket`, `DELETE /v1/realtime/ticket`
A service health, readiness or contract document probe, not an account or market capability.	`GET /health`, `GET /ready`, `GET /openapi.json`
A CCXT placeholder that always answers 501 NotSupported.	`GET /v2/not-implemented/fetch-trades`, `POST /v2/not-implemented/cancel-all-orders`, `PUT /v2/not-implemented/edit-order`, `GET /v2/not-implemented/fetch-funding-rate-history`, `GET /v2/not-implemented/fetch-funding-history`, `PUT /v2/not-implemented/set-leverage`, `PUT /v2/not-implemented/set-margin-mode`
The same capability in the CCXT wire shape; a tool serves its /v1 twin.	`GET /v2/markets` (twin `GET /v1/markets`), `GET /v2/markets/:symbol/stats` (twin `GET /v1/markets/:marketId/stats`), `GET /v2/markets/:symbol/candles` (twin `GET /v1/markets/:marketId/candles`), `GET /v2/markets/:symbol/book` (twin `GET /v1/markets/:marketId/book`), `GET /v2/accounts/:accountId` (twin `GET /v1/accounts/:accountId`), `GET /v2/accounts/:accountId/positions` (twin `GET /v1/accounts/:accountId/positions`), `POST /v2/order` (twin `POST /v1/orders`), `POST /v2/orders` (twin `POST /v1/orders/batch`), `GET /v2/orders/:orderId` (twin `GET /v1/orders/:orderId`), `POST /v2/orders/:orderId/cancel` (twin `POST /v1/orders/:orderId/cancel`), `POST /v2/orders/cancel` (twin `POST /v1/orders/batch/cancel`), `GET /v2/accounts/:accountId/orders` (twin `GET /v1/accounts/:accountId/orders`), `GET /v2/accounts/:accountId/orders/open` (twin `GET /v1/accounts/:accountId/orders/open`), `GET /v2/accounts/:accountId/fills` (twin `GET /v1/accounts/:accountId/fills`)

Closing submits a reduce-only market order through POST /v1/orders. Take profit and stop loss travel as autoClose (takeProfitPriceAtoms, stopLossPriceAtoms) on edel_place_order and on each edel_place_order_batch entry. The public contract has no standalone trigger arm, cancel or replace route and no timeInForce on /v1, so no tool offers them. edel_place_order requires a caller-supplied clientOrderId. Choose it once per owner-approved logical order and reuse it with identical arguments on every retry, including after a lost response. Never generate a new identity just because the API did not answer: it may already have accepted the order. Read-only history tools use the approved key: edel_order_history reads orders, edel_trade_history reads fills, and edel_position_history reads position episodes. Each returns one page (default 50, maximum 100), nextCursor and projection freshness; pass cursor to fetch the next page. All accept marketId; order and position history also accept status. edel_funding reads that same paginated position history with market/status filters and labels its basis cumulative_per_position_episode: fundingPaidAtoms is cumulative funding paid per episode. It is not per-payment funding history; the API does not serve that ledger, and this tool never invents payment rows.

What a key can do

Scope	What it allows
`read`	The account snapshot, KYC status, positions, one order or all of them, fills, order previews, Party binding status and a realtime ticket. Markets need no key.
`trade`	Everything `read` allows, plus placing and cancelling orders, one at a time or in batches.

A key never deposits, withdraws, changes the Party binding, approves another agent or manages keys, and it does not read transfers or affiliate data or edit favorites. Those routes answer 403 with apiKeyRejection set to passkey_required; a read key placing an order gets scope_insufficient. A key expires (24 hours by default, 7 days at most) and the owner can revoke it. A refused key answers 401 with apiKeyRejection set to expired, revoked, unknown or malformed: connect again.

Identity is not account readiness

Prerequisite	What it establishes
Signing identity	The DFNS end-user passkey and delegated signing key. Login proves the credential, not trading readiness.
Canton Party binding	Secure setup binds the on-ledger identity to the Edel account. Verify `active` before trading.

The human owner approves every required DFNS User Action with their passkey; an API key never replaces that approval. Funding and withdrawals stay with the owner. No step here guarantees a successful live flow. Keep connect codes and private identifiers in memory, never in command-line arguments, logs, files or chat. The API key is the one credential you keep in a file, and only you may read that file.

Shared reference

Use the REST API reference for request and response contracts. Use WebSockets, not REST polling, for live data; follow the shared channel documentation.

​Start here

​Connect with an API key

​Use the Edel MCP server

​Direct remote client (preferred)

​Optional local bridge

​Tools and their REST operations

​What a key can do

​Identity is not account readiness

​Shared reference