Execute currency exchange

Delegated Contract Mode will be deprecated soon; new partners should use Managed Custody Mode. Exchanges one fiat token balance for another on behalf of the user. Amounts are smallest-unit strings (100.00 USD is "10000"). requestId is the idempotency key; keep it stable across retries.

post

/v1/exchange

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

urIdinteger · int64Required

UR user ID.

inputTokenstringRequired

Input token symbol from /v1/tokens.

outputTokenstringRequired

Output token symbol from /v1/tokens.

amountstringRequired

Exchange amount in smallest units.

requestIdstringRequired

Idempotency key; reuse on retry.

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

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

{
  "urId": 12345,
  "inputToken": "USD",
  "outputToken": "EUR",
  "amount": "10000",
  "requestId": "req-20240101-0001"
}

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..."
  }
}