Express Intent Tool

What problem it solves

The express-intent tool lets users create an Indication of Interest (IOI) through natural language. Instead of filling a form, they tell the LLM "I want to buy 1000 shares of position X" or "Express my interest in selling position Y to participant Z." The tool creates the IOI in DMTR, enabling transfer workflows to proceed. It bridges conversational AI and the DMTR transfer pipeline.

Input schema

{
  "position_id": "string (required) - Position to transfer",
  "buyer_participant_id": "string (required) - Buyer (or seller for sell-side)",
  "quantity": "number (required) - Quantity to transfer",
  "side": "string (required) - buy | sell",
  "idempotency_key": "string (optional) - Idempotency key for safe retries",
  "metadata": "object (optional) - Custom metadata"
}

The tool creates an IOI; it does not execute the transfer. The transfer is executed separately via the DMTR API or workflows.

Output schema

{
  "ioi_id": "string - Created IOI ID",
  "status": "string - pending | accepted | rejected",
  "message": "string - Confirmation message"
}

Idempotency

Idempotent when idempotency_key is provided. Same key returns the same IOI; duplicate creation is prevented. Without idempotency key, each call creates a new IOI.

Side effects

Creates an IOI in DMTR. This is a write operation. The IOI may trigger notifications, workflows, or downstream processes. Use with care in automated contexts.

Required scopes

• positions:read
• participants:read
• ioi:write (or transfers:write)

Safe and unsafe contexts

Unsafe in automated/batch contexts without idempotency keys. Safe for user-initiated conversational flows. Do not call repeatedly without user confirmation; each call creates an IOI.

Expected latency

Typically 200–600 ms. Includes IOI creation and validation.

Example usage

Input: { "position_id": "pos_abc", "buyer_participant_id": "part_xyz", "quantity": 1000, "side": "buy", "idempotency_key": "user-123-intent-1" }

Output: { "ioi_id": "ioi_def456", "status": "pending", "message": "IOI created. Awaiting seller response." }

Common failure modes

• 409 Conflict: Transfer not feasible (e.g., encumbrance, consent required). Use evaluate-transfer first.
• 422 Validation: Invalid quantity or participant. Check input.
• Idempotency conflict: Key already used with different params. Use unique key or same params.

Audit records emitted

DMTR emits ioi.created audit event. Full audit trail for compliance.