Intent

How to submit an Intent, receive a firm quote, and confirm execution.

Flow

POST /v1/intents → quoted → POST /v1/intents/{id}/confirm → executing → settled

Step 1: Submit an Intent

Declare what you want to exchange and your constraints. Ezys returns a firm quote.

Request

{
  "pair": {
    "source": "USDC",
    "target": "KRW"
  },
  "amount": "1000",
  "strategy": "instant",
  "constraints": {
    "maxSlippageBps": 50,
    "maxFeeBps": 30,
    "settlementPref": "hybrid"
  },
  "clientRef": "your-reference-id"
}

clientRef is an opaque label you attach for your own bookkeeping — the gateway echoes it back but does not use it for deduplication. To make a submission safe to retry (exactly-once), send an Idempotency-Key header as well — see Idempotency.

Response

The response includes a firm quote valid until expiresAt.

{
  "success": true,
  "data": {
    "intentId": "int_2f8a3b1c",
    "status": "quoted",
    "quote": {
      "rate": "1424.50",
      "outputAmount": "1424500.00",
      "fees": {
        "totalBps": 25,
        "amount": "2.50"
      }
    },
    "expiresAt": "2025-01-29T12:00:30Z"
  }
}

At this point, nothing has been executed. You have a firm rate and can decide whether to proceed.

Step 2: Confirm

If the quote is acceptable, confirm to lock in the rate and trigger execution.

POST /v1/intents/int_2f8a3b1c/confirm

Once confirmed, the Intent moves to executing and settlement begins. The quoted rate is locked — no price changes between confirmation and settlement.

Step 3: Track Status

Poll the Intent to track progress.

GET /v1/intents/int_2f8a3b1c

Status	What it means
quoted	Quote received, waiting for your confirmation
executing	Confirmed, settlement in progress
settled	Done — funds have been transferred
expired	You didn't confirm in time — submit a new Intent

Handling Expiry

Quotes are valid for a limited window. If you don't confirm before expiresAt, the Intent expires automatically. Simply submit a new Intent to get a fresh quote.

Cancellation

You can cancel an Intent while it's in quoted status:

DELETE /v1/intents/int_2f8a3b1c

Once the Intent enters executing, it cannot be cancelled.

Full API Reference

For complete field descriptions and error codes, see the Intent API.