Create on-ramp request

Delegated Contract Mode will be deprecated soon; new partners should use Managed Custody Mode. On-ramp is not yet generally available; this endpoint is documented for preview only. Exchanges a fiat token to USDC and optionally performs a swap or bridge to the target token based on the quote from /v1/onramp/quote. Omit the dst* fields to perform fiat to USDC only.

post

/v1/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

X-Api-SignaturestringRequired

Partner's EIP-191 signature (0x-prefixed hex).

X-Api-DeadlinestringRequired

Unix seconds when the request signature expires (within 5 minutes).

X-Api-PublicKeystringOptional

Partner's signer Ethereum address.

Body

quoteIdstringRequired

Quote ID from /v1/onramp/quote.

requestIdstringRequired

Idempotency key; reuse on retry.

urIdinteger · int64Required

UR user ID.

tokenInstringRequired

Fiat token symbol from /v1/tokens.

amountInstringRequired

Input amount in smallest units. After conversion, must be at least 5 USDC.

withdrawAddressstringOptional

User-specified withdrawal address for the on-ramp.

chainIdstringOptional

Source chain ID (currently Mantle only).

dstChainIdstringOptional

Destination chain ID for the bridge or swap.

dstAggregatorstringOptional

Aggregator contract address from best.aggregator in the quote.

dstTokenOutstringOptional

Destination token symbol.

dstSwapCalldatastringOptional

best.swapCalldata from the quote.

dstMinAmountOutstringOptional

Minimum acceptable amount in smallest units, from best.minUsdcAmount.

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 partner API (openapi.ur.app).

codeinteger · int64Required

0 on success; non-zero indicates a business rejection.

messagestringRequired

Human-readable diagnostic; empty on success.

dataanyOptional

Business payload. Shape depends on the endpoint.

post/v1/onramp

POST /v1/onramp HTTP/1.1
Host: openapi.ur.app
X-Api-Signature: text
X-Api-Deadline: text
Content-Type: application/json
Accept: */*
Content-Length: 189

{
  "quoteId": "onramp_1700000000000000000",
  "requestId": "onramp-demo-001",
  "urId": 7639951412,
  "chainId": "eip155:5000",
  "tokenIn": "USD",
  "amountIn": "10000",
  "withdrawAddress": "0xUserWithdrawAddress"
}

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.

{
  "code": 0,
  "message": "",
  "data": {
    "txHash": "0x1234567890abcdef..."
  }
}