Execute Transfer Intent

What you will build

You will create an Indication of Interest (IOI), check transfer feasibility, submit a transfer intent, and monitor its status through to completion. This quickstart covers the core transfer workflow.

Prerequisites

• API key with positions:read, intent:read, intent:write scopes
• At least one position in your inventory (sandbox has seed data)
• Understanding of Position Object and Transferability

Steps to create IOI

Create an IOI via POST /intents/ioi with the position entity_id, quantity or percentage, and optional terms. The API validates the position exists and returns an IOI object with a unique ID. Use this ID for subsequent steps.

Check transfer feasibility

Before submitting the intent, call the Rights Engine or feasibility endpoint to check if the transfer is allowed. You receive restrictions, consent requirements, and blocking issues. Address any blockers (e.g., obtain consent) before proceeding.

Submit intent

Submit the transfer intent via POST /intents (or equivalent) with the IOI ID and required metadata. Include an Idempotency-Key for safe retries. The API returns an intent object with status pending or submitted.

curl -X POST "https://sandbox-api.dmtr.ai/v1/intents" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "position_id": "meg-2026-047",
    "type": "sell",
    "quantity": 5,
    "price_per_unit": 25000
  }'

Monitor status

Poll GET /intents/{id} or subscribe to webhooks for transfer.intent_created, transfer.consent_updated, transfer.completed. Status progresses through consent, matching, and execution. Handle rejected or cancelled appropriately.

Next steps

• Execute a Transfer — Full transfer guide with consent chain
• Implement Intent Capture — IOI routing and matching
• Webhooks — Real-time event notifications