Pairs

Exact pair metadata and counterpart-token search (GET /v1/pairs, GET /v1/pairs/search)

Search available exchange pairs

get

/v1/pairs

Returns metadata for one exact direction. All four query fields are required: fromToken, fromNetwork, toToken, toNetwork.

Each pair includes availableEngines (on-chain / off-chain / private), provider slugs, minAmount and maxAmount ("0" when the catalog has no max).

Unknown token/network combinations that still pass validation return { tokenPairs: [], totalPairs: 0 } (200), not 404.

Successful lookups are cached for 5 minutes. To list counterpart tokens for a single side, use GET /v1/pairs/search.

Query parameters

fromTokenstringRequired

Source token ticker. Must be provided together with fromNetwork.

Example: ETH

fromNetworkstringRequired

Source chain slug (GET /v1/chains → id)

Example: ETH

toTokenstringRequired

Target token ticker. Must be provided together with toNetwork.

Example: USDC

toNetworkstringRequired

Target chain slug (GET /v1/chains → id)

Example: ETH

Responses

200

Matching token pairs (often 0 or 1) with engines and limits

application/json

totalPairsnumberRequired

Total number of token pairs found

Example: 1

400

Missing required field or unknown query parameter

application/json

408

WORKFLOW_TIMEOUT (20s pair workflow)

application/json

500

TOKEN_PAIRS_ERROR or workflow failure

application/json

get/v1/pairs

GET /v1/pairs?fromToken=ETH&fromNetwork=ETH&toToken=USDC&toNetwork=ETH HTTP/1.1
Host: api.yifi.io
Accept: */*

{
  "tokenPairs": [
    {
      "fromToken": "ETH",
      "fromNetwork": "ETH",
      "toToken": "USDC",
      "toNetwork": "ETH",
      "availableEngines": [
        "on-chain",
        "off-chain",
        "private"
      ],
      "providers": [
        "lifi",
        "quickex",
        "houdini"
      ],
      "minAmount": "0.01",
      "maxAmount": "100"
    }
  ],
  "totalPairs": 1
}

Search available counterpart tokens for a pair

get

/v1/pairs/search

Paginated counterpart tokens for building a pair picker. Response shape matches GET /v1/tokens.

How filters are applied (no 400 for a lone ticker/network):

• fromToken and fromNetwork both set → tokens you can receive (the to side of catalog pairs). Optional toNetwork further restricts those counterparts.

• toToken and toNetwork both set → tokens you can send (the from side). Optional fromNetwork further restricts those counterparts.

• Only one side of a pair (fromToken without fromNetwork, etc.) is treated as not set.

• Neither complete side → the counterpart set is empty (tokens: [], total: 0). This endpoint does not dump the full catalog.

search ranks within the counterpart set (ticker / name / address). Default page: limit=20, offset=0. Coin-set cache TTL: 5 minutes.

Query parameters

fromTokenstringOptional

Source token ticker. Used only when fromNetwork is also set; otherwise ignored.

Example: ETH

fromNetworkstringOptional

Source chain slug. Used only when fromToken is also set; otherwise ignored.

Example: ETH

toTokenstringOptional

Target token ticker. Used only when toNetwork is also set; otherwise ignored.

Example: USDC

toNetworkstringOptional

Target chain slug. Used only when toToken is also set; otherwise ignored.

Example: ETH

searchstringOptional

Search by ticker or token name within the results

Example: BTC

limitnumber · min: 1 · max: 100Optional

Number of results per page. Maximum 100.

Default: 20Example: 20

offsetnumberOptional

Pagination offset

Default: 0Example: 0

Responses

200

Paginated counterpart tokens

application/json

totalTokensnumberRequired

Number of token objects in this response page (matches tokens.length)

limitnumberRequired

Page size for this response

offsetnumberRequired

Pagination offset

totalnumberRequired

Total tokens matching filters before pagination

400

Invalid pagination or unknown query parameter

application/json

408

WORKFLOW_TIMEOUT (20s pair workflow)

application/json

500

TOKEN_PAIRS_ERROR or workflow failure

application/json

get/v1/pairs/search

GET /v1/pairs/search HTTP/1.1
Host: api.yifi.io
Accept: */*

{
  "tokens": [
    {
      "uuid": "4f2e6d6b-6e15-4f47-8b6e-2a3d3c5b9d10",
      "network": "ETH",
      "ticker": "ETH",
      "name": "Ethereum",
      "supportsFixedRate": false,
      "contractAddress": null,
      "engineSupport": [
        "on-chain",
        "off-chain"
      ],
      "logoUrlCoin": "text",
      "regexAddress": "^0x[a-fA-F0-9]{40}$",
      "explorerAddressUrl": "text",
      "explorerTransactionUrl": "text",
      "decimals": {},
      "logoUrlsNetwork": {},
      "coingeckoCoinId": "ethereum",
      "currentPriceUsd": "2397.32"
    }
  ],
  "totalTokens": 1,
  "limit": 1,
  "offset": 1,
  "total": 1
}