Get on-ramp quote

On-ramp is not yet generally available; this endpoint is documented for preview only. Returns a quote for scene onramp (fiat token to destination token) or scene swap_retry (retry a failed destination swap). When needLiveness is true, the user must pass liveness before submitting.

post

/api/v1/quote/onramp

Authorizations

X-Api-SignaturestringRequired

Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide.

Header parameters

tokenIdstringRequired

The user's URID (NFT token id).

networkstringRequired

Network identifier: 5000 for mainnet, 5003 for testnet.

signstringRequired

Signature generated by the user's wallet key (EIP-191).

hashstringRequired

SHA3/Keccak256 hash of the original request payload.

deadlinestringRequired

Signature expiry: server timestamp plus a validity window (max 20 minutes).

Body

scenestring · enumRequired

onramp for the main flow; swap_retry for retrying a failed swap leg.

Possible values:

srcChainIdstringRequired

Source chain ID (CAIP-2).

dstChainIdstringRequired

Destination chain ID (CAIP-2).

fromTokenstringRequired

Fiat token contract address.

toTokenstringRequired

Destination token address.

amountstringRequired

Input amount in smallest units (e.g. "10000" is 100 USD).

slippageBpsintegerOptional

Slippage tolerance in basis points.

Responses

200

Response envelope. For the user API, retCode 0 means success; for the partner API, code 0 means success. Business rejections return HTTP 200 with a non-zero code.

application/json

Standard response envelope for the user API (api.ur.app).

retCodeinteger · int64Required

0 on success; non-zero indicates failure.

retMsgstringRequired

Human-readable message; error details when retCode is non-zero.

resultanyOptional

Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string.

timeNowinteger · int64Optional

Server timestamp in milliseconds.

post/api/v1/quote/onramp

POST /api/v1/quote/onramp HTTP/1.1
Host: api.ur.app
X-Api-Signature: YOUR_API_KEY
tokenId: text
network: text
sign: text
hash: text
deadline: text
Content-Type: application/json
Accept: */*
Content-Length: 181

{
  "scene": "onramp",
  "srcChainId": "eip155:5000",
  "dstChainId": "eip155:8453",
  "fromToken": "0xFiatTokenAddress",
  "toToken": "0xDestinationTokenAddress",
  "amount": "100000000",
  "slippageBps": 50
}

200

Response envelope. For the user API, retCode 0 means success; for the partner API, code 0 means success. Business rejections return HTTP 200 with a non-zero code.

{
  "retCode": 0,
  "retMsg": "success",
  "result": {
    "quoteId": "onramp_direct_1703123000000_12345",
    "best": {
      "aggregator": "1inch",
      "to": "0xAggregatorAddress",
      "swapCalldata": "0x....",
      "expectedAmountOut": "1234500",
      "minAmountOut": "1228327",
      "slippageBps": 50,
      "deadline": 1703123600
    },
    "outputAmount": "1.2345",
    "needLiveness": true,
    "networkFee": "0.43"
  },
  "timeNow": 1703123456789
}