Transactions

Poll status and submit an on-chain deposit hash

Get transaction status

get

/v1/transactions/{id}

Returns the current status of an order created via POST /v1/swap.

id is the YiFi UUID from transactionId in the create-swap response. A provider order id is not accepted and returns 404 TRANSACTION_NOT_FOUND. Empty / whitespace id → 400 INVALID_TRANSACTION_UUID.

Token fields are expanded to objects (ticker, network, logos, contractAddress, chainId, decimals). inputAmount is the stored deposit amount. exchangeRate is receiveAmount / inputAmount when both parse as numbers and input > 0; otherwise null.

fee from storage is not returned. Extra workflow fields that are returned when present: txDepositHash, txOutputHash, depositAddress, receiveAddress, statusList.

There is no access_token query on this public route when id is a YiFi UUID (unlike api-gateway).

Top-level status: pending → processing → completed, or failed / cancelled. statusList keys are provider-specific booleans.

Path parameters

idstringRequired

YiFi transaction UUID from POST /v1/swap → transactionId. Provider order ids are rejected.

Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses

200

Transaction details and current status

application/json

uuidstringRequired

YiFi UUID. Same value as POST /v1/swap → transactionId and as the path {id} you queried.

Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

transactionIdstringRequired

Provider-side transaction id (may differ from uuid)

Example: 1ad576f82276a5

statusstring · enumRequired

Current top-level swap status

Example: completedPossible values:

statusListobjectOptional

Granular step-by-step status map. Keys vary by provider and engine.

Example: {"waitingForDepositToProvider":true,"depositConfirmByProvider1":true}

enginestring · enumRequired

Swap engine used for this transaction

Example: off-chainPossible values:

providerstringRequired

Provider slug executing this swap

Example: providerX

logoProviderobjectOptional

Provider logo URL

Example: https://example.com/logo.png

inputAmountstringRequired

Amount sent by the user in source token units

Example: 1.0

receiveAmountstringRequired

Amount received (or expected) in target token units

Example: 1850.25

startTimestringOptional

Timestamp when the transaction was created

Example: 2024-01-15T10:00:00Z

completionTimestringOptional

Timestamp when the transaction reached a terminal state (completed, failed, or cancelled). null while in progress.

Example: 2024-01-15T10:03:00Z

exchangeRateobject · nullableOptional

Effective exchange rate (receiveAmount / inputAmount). Populated once the swap reaches completed status.

Example: 1850.25

expirationTimeobject · nullableOptional

Order expiration captured at swap creation (same as in create-swap response; mapped via exchanger expirationTimePath)

Example: 2025-12-01T12:00:00.000Z

txCreateMetaobjectOptional

Raw provider metadata from transaction creation. May be an empty object or JSON string.

txDepositHashobject · nullableOptional

On-chain deposit hash once known. null / omitted while waiting.

Example: 0xabc123…

txOutputHashobject · nullableOptional

On-chain output / payout hash once known. null / omitted while waiting.

depositAddressobject · nullableOptional

Deposit address the user must send to (CEX / private)

receiveAddressobject · nullableOptional

Destination address that receives the output token

400

INVALID_TRANSACTION_UUID (empty id)

application/json

404

TRANSACTION_NOT_FOUND

application/json

408

WORKFLOW_TIMEOUT (30s)

application/json

500

INCOMPLETE_TRANSACTION_DATA or TRANSACTION_STATUS_ERROR

application/json

get/v1/transactions/{id}

GET /v1/transactions/{id} HTTP/1.1
Host: api.yifi.io
Accept: */*

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "transactionId": "1ad576f82276a5",
  "status": "completed",
  "statusList": {
    "waitingForDepositToProvider": true,
    "depositConfirmByProvider1": true
  },
  "engine": "off-chain",
  "provider": "providerX",
  "logoProvider": "https://example.com/logo.png",
  "fromToken": {
    "ticker": "USDT",
    "network": "ethereum",
    "logoTicker": {},
    "logoNetwork": {},
    "contractAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    "chainId": 1,
    "decimals": 6
  },
  "toToken": {
    "ticker": "USDT",
    "network": "ethereum",
    "logoTicker": {},
    "logoNetwork": {},
    "contractAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    "chainId": 1,
    "decimals": 6
  },
  "inputAmount": "1.0",
  "receiveAmount": "1850.25",
  "startTime": "2024-01-15T10:00:00Z",
  "completionTime": "2024-01-15T10:03:00Z",
  "exchangeRate": "1850.25",
  "expirationTime": "2025-12-01T12:00:00.000Z",
  "txCreateMeta": {},
  "txDepositHash": "0xabc123…",
  "txOutputHash": {},
  "depositAddress": {},
  "receiveAddress": {}
}

Submit deposit transaction hash

post

/v1/transactions/{transactionProvider}/{engine}/set-deposit-hash

Forwards { from, to, hash } to setDepositHashWorkflow after the user broadcasts a DEX deposit.

Query access_token is required (the secret from POST /v1/swap). Missing token → 400 ACCESS_TOKEN_REQUIRED without an order lookup.

transactionProvider is the provider order id passed to the workflow as transactionId.

engine is case-insensitive and must be dex. cex and private → 400 INVALID_ENGINE and the workflow is not started.

The hash is stored once. The same hash returns true without rewriting. A different hash → 409 DEPOSIT_HASH_ALREADY_SET.

Optional body field input is passed through as workflow meta.data.

Success body is JSON true (201).

Path parameters

transactionProviderstringRequired

Provider-side transaction id / slug passed to setDepositHashWorkflow as transactionId

Example: quickex

enginestring · enumRequired

Must be dex. Other engines are rejected.

Example: dexPossible values:

Query parameters

access_tokenanyRequired

Order access token returned by POST /v1/swap

Body

fromstringRequired

Sender wallet address that broadcast the deposit

Example: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

tostringRequired

Deposit destination: provider deposit address (CEX/private) or the contract the user sent to (DEX)

Example: 0x1111111254fb6c44bac0bed2854e76f90643097d

hashstringRequired

On-chain transaction hash of the broadcast deposit

Example: 0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890

inputobjectOptional

Optional raw input forwarded to the provider workflow as meta.data. Shape is provider-specific.

Responses

201

Workflow returned success (true)

application/json

booleanOptionalExample: true

400

Invalid engine, missing access_token, or from / to / hash missing or not strings (INVALID_BODY)

application/json

500

DEX_NOT_CONFIGURED or WORKFLOW_EXECUTION_FAILED

application/json

post/v1/transactions/{transactionProvider}/{engine}/set-deposit-hash

POST /v1/transactions/{transactionProvider}/{engine}/set-deposit-hash?access_token=null HTTP/1.1
Host: api.yifi.io
Content-Type: application/json
Accept: */*
Content-Length: 189

{
  "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "to": "0x1111111254fb6c44bac0bed2854e76f90643097d",
  "hash": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
  "input": {}
}

true

PreviousSwap

NextModels

Last updated 2 days ago

Was this helpful?