Intent API

Intent 제출 및 견적 조회를 위한 API 명세입니다.

Create Intent

거래 의도(Intent)를 제출합니다. EZYS가 자동으로 최적 실행을 진행합니다.

Endpoint

POST /v1/intents

Request

{
  "pair": {
    "source": "USDC",
    "target": "KRW"
  },
  "side": "sell",
  "amount": "1000",
  "strategy": "instant",
  "constraints": {
    "maxSlippageBps": 50,
    "maxFeeBps": 30,
    "settlementPref": "auto",
    "ttlMs": 30000
  },
  "clientRef": "REMIT-20240123-001"
}

Request Fields

필수

Field

Type

Description

pair.source

string

출발 자산 (예: USDC, USD)

pair.target

string

도착 자산 (예: KRW, USD)

side

string

sell (source → target)

amount

string

source 기준 금액

strategy

string

실행 전략: instant, optimized, scheduled

Constraints (선택)

Field

Type

Default

Description

constraints.maxSlippageBps

number

50

허용 최대 슬리피지 (bps)

constraints.maxFeeBps

number

30

허용 최대 수수료 (bps)

constraints.settlementPref

string

auto

onchain, offchain, auto

constraints.ttlMs

number

30000

유효기간 (밀리초)

기타 (선택)

Field

Type

Description

clientRef

string

FSP 측 참조 번호

Note: actor 정보(FSP ID, type)는 API Key에서 자동으로 식별됩니다.

Strategy

설명

instant

가능한 빠르게 체결을 시도합니다. 높은 우선순위로 처리됩니다.

optimized

더 나은 가격을 위해 여러 윈도우(epoch)에 걸쳐 최적 경로를 탐색합니다.

scheduled

지정된 조건이나 시점까지 대기 후 처리됩니다.

Intent는 하나의 윈도우에서 전체가 체결되지 않을 수 있습니다. 여러 윈도우에 걸쳐 부분 체결되며, 전체 금액이 처리될 때까지 진행됩니다.

Example Request

curl -X POST "https://api.ezys.io/v1/intents" \
  -H "X-API-Key: ezys_live_sk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "pair": { "source": "USDC", "target": "KRW" },
    "side": "sell",
    "amount": "1000",
    "strategy": "instant",
    "constraints": { "maxSlippageBps": 50, "maxFeeBps": 30 },
    "clientRef": "TIKO-TX-12345"
  }'

Response

{
  "success": true,
  "data": {
    "intentId": "int_2f8a3b1c",
    "clientRef": "TIKO-TX-12345",
    "status": "solving",
    "actor": {
      "id": "tikopay",
      "type": "retail"
    },
    "pair": {
      "source": "USDC",
      "target": "KRW"
    },
    "side": "sell",
    "amount": "1000",
    "strategy": "instant",
    "constraints": {
      "maxSlippageBps": 50,
      "maxFeeBps": 30,
      "settlementPref": "auto",
      "ttlMs": 30000
    },
    "createdAt": "2025-01-29T12:00:00Z",
    "expiresAt": "2025-01-29T12:00:30Z"
  }
}

Get Intent

Intent 상태 및 결과를 조회합니다.

Endpoint

GET /v1/intents/{intentId}

Path Parameters

Parameter

Type

Description

intentId

string

Intent ID

Example Request

curl -X GET "https://api.ezys.io/v1/intents/int_2f8a3b1c" \
  -H "X-API-Key: ezys_live_sk_xxxxx"

Response (settled)

{
  "success": true,
  "data": {
    "intentId": "int_2f8a3b1c",
    "clientRef": "TIKO-TX-12345",
    "status": "settled",
    "actor": {
      "id": "tikopay",
      "type": "retail"
    },
    "pair": {
      "source": "USDC",
      "target": "KRW"
    },
    "side": "sell",
    "amount": "1000",
    "strategy": "instant",
    "execution": {
      "executedRate": "1424.50",
      "inputAmount": "1000.00",
      "outputAmount": "1424500.00",
      "fees": {
        "totalBps": 25,
        "amount": "2.50"
      },
      "timestamp": "2025-01-29T12:00:01Z"
    },
    "settlement": {
      "settleId": "stl_m1n2o3",
      "type": "type_a",
      "status": "completed",
      "legs": [
        {
          "legIndex": 0,
          "type": "onchain",
          "chain": "ethereum",
          "asset": "USDC",
          "amount": "1000.00",
          "direction": "outflow",
          "status": "completed",
          "txHash": "0xabc123..."
        },
        {
          "legIndex": 1,
          "type": "offchain",
          "asset": "KRW",
          "amount": "1424500.00",
          "direction": "inflow",
          "status": "completed",
          "providerRef": "BANK_TXN_456"
        }
      ],
      "completedAt": "2025-01-29T12:00:10Z"
    },
    "createdAt": "2025-01-29T12:00:00Z"
  }
}

Intent Status

Status

Description

pending

Intent 제출됨

solving

Solver Network 처리 중

queued

Epoch 대기 중 (scheduled)

executing

실행 확정, Settlement 진행 중

settled

Settlement 완료

expired

TTL 초과

rejected

constraints 불충족 또는 유동성 부족

cancelled

사용자 취소

List Intents

Intent 목록을 조회합니다.

Endpoint

GET /v1/intents

Query Parameters

Parameter

Type

Default

Description

status

string

상태 필터

strategy

string

전략 필터

fromDate

string

시작 일시 (ISO 8601)

toDate

string

종료 일시 (ISO 8601)

page

number

1

페이지 번호

limit

number

20

페이지당 항목 수 (max: 100)

Example Request

curl -X GET "https://api.ezys.io/v1/intents?status=settled&limit=10" \
  -H "X-API-Key: ezys_live_sk_xxxxx"

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "intentId": "int_2f8a3b1c",
        "clientRef": "TIKO-TX-12345",
        "status": "settled",
        "pair": {
          "source": "USDC",
          "target": "KRW"
        },
        "amount": "1000",
        "strategy": "instant",
        "execution": {
          "executedRate": "1424.50",
          "outputAmount": "1424500.00"
        },
        "createdAt": "2025-01-29T12:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 45,
      "totalPages": 5
    }
  }
}

Cancel Intent

실행 전 Intent를 취소합니다. executing 이후에는 취소할 수 없습니다.

Endpoint

DELETE /v1/intents/{intentId}

Path Parameters

Parameter

Type

Description

intentId

string

Intent ID

Example Request

curl -X DELETE "https://api.ezys.io/v1/intents/int_2f8a3b1c" \
  -H "X-API-Key: ezys_live_sk_xxxxx"

Response

{
  "success": true,
  "data": {
    "intentId": "int_2f8a3b1c",
    "status": "cancelled",
    "cancelledAt": "2025-01-29T12:00:05Z"
  }
}

Error Responses

Invalid Pair

{
  "success": false,
  "error": {
    "code": "INVALID_PAIR",
    "message": "Unsupported pair: ABC/XYZ"
  }
}

Invalid Strategy

{
  "success": false,
  "error": {
    "code": "INVALID_STRATEGY",
    "message": "Invalid strategy: unknown. Must be instant, optimized, or scheduled"
  }
}

Constraints Not Met

{
  "success": false,
  "error": {
    "code": "CONSTRAINTS_NOT_MET",
    "message": "No execution path meets maxSlippageBps: 10"
  }
}

Insufficient Liquidity

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_LIQUIDITY",
    "message": "Insufficient liquidity for amount: 50000000"
  }
}

Intent Not Found

{
  "success": false,
  "error": {
    "code": "INTENT_NOT_FOUND",
    "message": "Intent not found: int_invalid"
  }
}

Intent Already Executing

{
  "success": false,
  "error": {
    "code": "INTENT_ALREADY_EXECUTING",
    "message": "Cannot cancel: intent is already executing"
  }
}

Intent Expired

{
  "success": false,
  "error": {
    "code": "INTENT_EXPIRED",
    "message": "Intent has expired"
  }
}

PreviousQuote API

Last updated 14 days ago

hashtagCreate Intent

hashtagEndpoint

hashtagRequest

hashtagRequest Fields

hashtag필수

hashtagConstraints (선택)

hashtag기타 (선택)

hashtagStrategy

hashtagExample Request

hashtagResponse

hashtagGet Intent

hashtagEndpoint

hashtagPath Parameters

hashtagExample Request

hashtagResponse (settled)

hashtagIntent Status

hashtagList Intents

hashtagEndpoint

hashtagQuery Parameters

hashtagExample Request

hashtagResponse

hashtagCancel Intent

hashtagEndpoint

hashtagPath Parameters

hashtagExample Request

hashtagResponse

hashtagError Responses

hashtagInvalid Pair

hashtagInvalid Strategy

hashtagConstraints Not Met

hashtagInsufficient Liquidity

hashtagIntent Not Found

hashtagIntent Already Executing

hashtagIntent Expired

Create Intent

Endpoint

Request

Request Fields

필수

Constraints (선택)

기타 (선택)

Strategy

Example Request

Response

Get Intent

Endpoint

Path Parameters

Example Request

Response (settled)

Intent Status

List Intents

Endpoint

Query Parameters

Example Request

Response

Cancel Intent

Endpoint

Path Parameters

Example Request

Response

Error Responses

Invalid Pair

Invalid Strategy

Constraints Not Met

Insufficient Liquidity

Intent Not Found

Intent Already Executing

Intent Expired