OpenAPIs

API Configurations

Base URLs

The API is deployed across different environments. Please use the appropriate base URL for your integration stage .

Environment	Base URL
Testnet	https://uropenapi.s7.gomantle.org
Production	https://openapi.ur.app

API Authentication

The authentication method for the following Core Banking APIs refers to this document.

Mint URID

Endpoint: POST /v1/mint/nft

Allows the Partner to create a registered user in the UR system via an API call and simultaneously mint a UR-Bank NFT ID for the user.

Before calling this endpoint, first query the Account NFT contract with tokenOfOwnerByIndex to check whether the user address already owns an NFT:

• If an NFT already exists, reuse the existing tokenId and do not call mint again

• If no NFT exists, call this endpoint to mint a new URID

Calling mint for an address that already has an NFT can return 10005 (Duplicate Mint).

Request Parameters:

{
  "email": "[email protected]",
  "evmAddress": "0xD4FcD82E3589b81A6de532e92E574761CC619531",
  "signature": "0x7f561411c39e993c807cd49d336e32bc2ec5e9ca12035a7efaa724ca760f97dc66f45a73b1b5dbf605127ee9ec5989e88972ba6c9a09d3684b0dec436229cc2701",
  "hash": "test-hash-1768792402",
  "deadline": "1768792702"
}

Field	Type	Required	Description
email	string	Yes	User's email address
evmAddress	string	Yes	User's EVM Wallet Address
signature	string	Yes	User's wallet signature (EIP-191). See User Authentication for signing details
hash	string	Yes	A Keccak256 hash of the business payload or a unique message
deadline	string	Yes	Unix timestamp (seconds) for signature expiration

User Signature Generation:

1. Construct base message: baseMessage = hash + deadline (string concatenation)

2. Generate intermediate hash: intermediateHash = Keccak256(baseMessage)

3. Construct final message: finalMessage = "I agree to access my profile. " + intermediateHash.hex()

4. User signs the finalMessage using their wallet (EIP-191)

For detailed signing and verification rules, please refer to Signature and Verification.

Response Example:

{
  "code": 0,
  "message": "success",
  "data": {
    "tokenId": 6021634448,
    "txHash": "0xb21c3e15de2f85fad9b04729f6db9ed6477fe08524b4db91a8e35ef2ab08039e"
  }
}

Response Field Description:

• tokenId: The minted NFT Token ID, required for all subsequent API calls

• txHash: On-chain transaction hash

Fetch UR Account Information

Endpoint: POST /v1/profile

Get user profile information including on-chain status and ERC20 authorization information.

Request Parameters:

{
  "urId": 12345,
  "authCode": "UAC_a1b2c3"
}

Field	Type	Required	Description
urId	int64	No	UR user ID, can directly query on-chain information
authCode	string	No	OAuth authorization code for future extension (can exchange via authorization code when urId is missing)

Note: At least one of urId or authCode must be provided. Currently, the endpoint primarily uses urId for queries, authCode field is for future authorization code extension scenarios.

Response Example:

{
  "code": 0,
  "message": "",
  "data": {
    "urId": 12345,
    "chainStatus": 5,
    "evmAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "usedLimit": 120000000,
    "clientLimit": 500000000,
    "startLimitDate": 1714377600,
    "allowances": [
      {
        "tokenSymbol": "USD",
        "hasAllowance": true
      },
      {
        "tokenSymbol": "EUR",
        "hasAllowance": true
      },
      {
        "tokenSymbol": "CHF",
        "hasAllowance": false
      },
      {
        "tokenSymbol": "JPY",
        "hasAllowance": true
      },
      {
        "tokenSymbol": "CNH",
        "hasAllowance": false
      },
      {
        "tokenSymbol": "SGD",
        "hasAllowance": false
      },
      {
        "tokenSymbol": "HKD",
        "hasAllowance": false
      }
    ],
    "kycRetryVerificationLevel": 0,
    "kycRetryVerificationLevelStr": "UNKNOWN",
    "kycCurrentStep": 0,
    "kycCurrentStepStr": "UNKNOWN"
  }
}

Response Field Description:

• urId: UR NFT ID

• chainStatus: On-chain status

  • 1 - SoftBlocked

  • 2 - Tourist

  • 3 - Blocked

  • 4 - Closed

  • 5 - Live (Normal)

• evmAddress: User's EVM address

• usedLimit: Current Accumulated Usage: The total volume used within the current 30-day billing cycle. This value is retrieved directly from the UR smart contract on-chain.

  • The value is denominated in CHF with 2 decimal places (e.g., a return value of 505 represents 5.05 CHF). This limit is incremented by all fiat-related operations, including Card Spending, FX, On-ramping, and Cash Payouts.

• clientLimit: Maximum Monthly Limit: The total spending capacity allocated to the user for a 30-day period.

  • The unit and retrieval method are identical to usedLimit. Any transaction (FX, Card Spending, On-ramp, or Cash Payout) that exceeds this threshold will be rejected by the smart contract. Partners are highly recommended to perform a pre-transaction check against the user's remaining limit (clientLimit - usedLimit) before initiating payment flows.

• startLimitDate: Limit start timestamp (seconds, UTC)

• allowances: ERC20 authorization list (batch queried on-chain via multicall)

  • tokenSymbol: Token symbol (USD, EUR, CHF, JPY, CNH, SGD, HKD)

  • hasAllowance: true if allowance has been set, otherwise false

• kycRetryVerificationLevel: KYC retry verification level (integer enum)

• kycRetryVerificationLevelStr: KYC retry verification level string

• kycCurrentStep: KYC current step (integer enum)

• kycCurrentStepStr: KYC current step string

**

KycRetryVerificationLevel Enum:

Value	Name	Description
0	UNKNOWN	Default value, Normal First KYC
1	ResetAll	Clear Sumsub + Sign, redo KYC + signature
2	ResetSumsub	Clear Sumsub KYC info, restart KYC
3	ResetSign	Clear signature info, re-sign
4	ResetGPS	Proactive GPS reset (created manually in admin)
5	RetryGPS	Passive GPS retry (auto-created when GPS fails) (Deprecated)
6	RetryVerificationPassport	Supplement passport info
7	ResetKYCToReadID	Reset KYC flow, use Sumsub + ReadID to redo KYC (Deprecated)

kycCurrentStep Enum:

Value	Name	Description
0	UNKNOWN	Default value
1	FormA	Form A step
2	IDScan	ID Scan step
3	SignFormA	Sign Form A
4	Review	Review step
5	Rejected	Rejected

Fetch UR Account Balance

Endpoint: POST /v1/balance

Get user balance information.

Request Parameters:

{
  "urId": 12345
}

Field	Type	Required	Description
urId	int64	Yes	UR user ID

Response Example:

{
  "code": 0,
  "message": "",
  "data": [
    {
      "symbol": "USDC",
      "amount": "1000.50"
    },
    {
      "symbol": "USD24",
      "amount": "5000.00"
    }
  ]
}

Response Field Description:

• symbol: Token symbol

• amount: Balance amount, formatted according to Token's Decimals precision (e.g., 2 or 6 decimal places)

Fetch Transaction History

POST /v1/transactions

Get user transaction records, supports multi-condition filtering and cursor pagination. The endpoint returns top-level pagination markers (hasNextPage, etc.) and structured information for each transaction.

Request Parameters:

{
  "urId": 7639951412,
  "chainId": "eip155:5000",
  "symbol": "USD24",
  "type": "P2P",
  "transactionTypes": ["P2P", "FRX"],
  "pageSize": 20,
  "fromTimestamp": 1701234567,
  "toTimestamp": 1704234567,
  "direction": "ALL",
  "minAmount": "1000",
  "maxAmount": "100000",
  "status": "completed",
  "currencies": ["USD", "EUR"],
  "cursorTimestamp": 1702000000,
  "cursorId": 123456789,
  "prevCursorTimestamp": 1701990000,
  "prevCursorId": 123456700
}

Field	Type	Required	Description
urId	int64	Yes	UR user ID
type	string	No	Single transaction type filter: P2P, FRX, CTU, CRD, CDP, CWP, CTF
transactionTypes	[]string	No	Multiple transaction types filter (mutually exclusive with type, which only supports a single value)
chainId	string	No	Chain ID (e.g., eip155:5000)
symbol	string	No	Token symbol (on-chain Token or fiat 24 series)
currencies	[]string	No	Fiat identifier array: EUR, USD, CHF, CNH
pageSize	int	No	Items per page, default 50, max 100
fromTimestamp / toTimestamp	int64	No	Time range filter, Unix seconds
direction	string	No	Transaction direction: IN, OUT, ALL
minAmount / maxAmount	string	No	Amount range filter (on-chain smallest unit string, follows amount description at the beginning of the document)
status	string	No	Transaction status filter (pending/completed/rejected/…)
cursorTimestamp / cursorId	int64	No	Cursor for next page pagination (obtained from previous page's nextCursor)
prevCursorTimestamp / prevCursorId	int64	No	Cursor for previous page pagination (optional)

Response Example:

{
  "code": 0,
  "message": "",
  "data": [
    {
      "title": "Transfer to Alice",
      "subtitle": "#7639",
      "amount": "-100.50",
      "type": "P2P",
      "timestamp": 1704234567,
      "currency": "USD",
      "direction": "OUT",
      "txHash": "0x21b4...",
      "chainId": "eip155:5000",
      "inputToken": "USD24",
      "inputAmount": "100.50",
      "status": "completed"
    },
    {
      "title": "Card Payment",
      "subtitle": "Merchant ABC",
      "amount": "-36.90",
      "type": "CRD",
      "timestamp": 1704234000,
      "currency": "USD",
      "direction": "OUT",
      "txHash": "0x3051...",
      "chainId": "eip155:5000",
      "mcc": 5812,
      "status": "pending"
    }
  ],
  "hasNextPage": true,
  "hasPrevPage": false,
  "nextCursor": {
    "timestamp": 1704233500,
    "id": 99887766
  },
  "prevCursor": {
    "timestamp": 1704235000,
    "id": 99887700
  },
  "currentPageSize": 2
}

Response Field Description:

Top-level fields

• code / message: Status code and description, 0 indicates success.

• data: Transaction records array.

• hasNextPage / hasPrevPage: Whether next/previous page exists.

• nextCursor / prevCursor: Pagination cursors (next page uses cursorTimestamp/cursorId, previous page uses prevCursorTimestamp/prevCursorId).

• currentPageSize: Number of entries returned in current page.

Each item in data array (same as /v1/transaction/query)

• title / subtitle: Display title information.

• amount: Amount string with sign to indicate direction.

• type: Transaction type abbreviation (P2P, FRX, CTU, CRD, CDP, CWP, CTF, etc.).

• timestamp: Transaction occurrence Unix seconds.

• currency: Token (USD24, EUR24, etc.).

• direction: IN / OUT.

• txHash: Transaction hash (if applicable).

• chainId: CAIP-2 chain identifier (e.g., eip155:5000).

• image: Transaction display icon or card logo.

• inputToken / inputAmount / inputTokenAddress: Original chain info for cross-chain transactions like CTU, CSW.

• outputAmount: Amount after FRX/CSW exchange.

• token / tokenAddress: Token and contract address involved in certain card or aggregated transactions.

• mcc, reference, bankAccount: Fields specific to card payments or bank transfers.

• crdMultiToken, ctuExternalSender, fromAddress, toAddress, etc.: Additional fields attached by transaction type.

• status: pending / completed / rejected / unknown.

• statusCode / crdCurrency: Card-returned status code, original currency, and other supplementary info.

• listingTitle, txHashUrl, txIdIcon, officialName: Supplementary fields for client display.

Fetch Transaction Details

POST /v1/transaction/query

Query aggregated transaction details based on on-chain transaction hash, supports single or multiple hashes.

Request Parameters:

{
  "txPairs": [
    {
      "urId": 7639951412,
      "txHash": "0x1234567890abcdef..."
    },
    {
      "urId": 7639951412,
      "txHash": "0xabcdefabcdefabcdef..."
    }
  ]
}

Field	Type	Required	Description
txPairs	array<object>	Yes	Query pairs, each item contains urId + txHash

Response Example:

{
  "code": 0,
  "message": "",
  "data": [
    // Each item follows the TransactionData structure, see "Public Data Structures" section
  ]
}

Response Field Description:

• code: Status code, 0 indicates success

• message: Status message, empty string "" when successful

• data: Array of transaction records, each item follows the TransactionData structure (see "Public Data Structures" section)

Notes:

• Returns code=0 only if all pairs are successfully queried; if any pair has no record, returns code=4001, message is transaction not found

• Each item in the returned array has the same structure as a single record in the /v1/transactions list