Ctrlk

OpenAPIs

Base URLs, environments, and authentication for all UR API endpoints.

API Configurations

Base URLs

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

Environment
Base URL

Testnet

https://uropenapi-qa.ur-inc.xyz

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:

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:

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

  • Generate intermediate hash: intermediateHash = Keccak256(baseMessage)

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

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

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

Response Example:

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:

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:

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

  • bankAccounts: Bank account information, keyed by currency code (e.g., CHF, EUR). Each currency maps to an array of bank account objects:

    • account: IBAN account number (generated based on user's NFT ID, Swiss CH IBAN format)

    • bankName: Bank name (e.g., SR Saphirstein AG)

    • bankAddress: Bank address

    • bic: SWIFT/BIC code (e.g., SAHHCHZ2)

  • crsInfo: CRS information :

    • needCrs: Indicates whether the user is required to complete the CRS process.

    • restrictDate: Represents the deadline or restriction timestamp for completing the CRS process, usually in Unix timestamp format (milliseconds). After this time, the user may be softBlocked.

    • url: The CRS submission link that directs the user to the CRS information collection page.

**

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:

Field
Type
Required
Description

urId

int64

Yes

UR user ID

Response Example:

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:

Field
Type
Required
Description

urId

int64

Yes

UR user ID

type

string

No

Single transaction type filter: P2P, FRX, CTU, CRD, CDP, CWD, 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:

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, CWD, 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.

The txHash field accepts both EVM transaction hashes (0x-prefixed hex) and Solana transaction signatures (Base58-encoded, 32–88 characters). The server auto-detects the format.

Request Parameters:

Field
Type
Required
Description

txPairs

array<object>

Yes

Query pairs, each item contains urId + txHash. txHash accepts EVM hex (0x…) or Solana Base58 signatures.

Response Example:

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

Create Sumsub Access Token By Network

Endpoint: POST /v1/create-access-token-by-network

Creates a Sumsub SDK access token for a specified tokenId on a given network. This endpoint is used to initiate KYC verification for users on external (non-Mantle) networks. The partner ID is automatically embedded into the Sumsub external user ID for traceability.

Prerequisites:

  • The partner must be whitelisted in Nacos (ur-other-sumsub-allowed-partners)

  • The on-chain walletProvider(tokenId) must match the requesting partner ID

Request Parameters:

Field
Type
Required
Description

tokenId

string

Yes

UR NFT token ID on the target network

network

string

Yes

Chain ID (e.g., "5000" for Mantle, "42161" for Arbitrum)

Response Example:

Response Field Description:

  • token: Sumsub SDK access token, used to initialize the Sumsub WebSDK on the client side

Error Codes:

Code
Description

10001

Partner not authenticated or not authorized

20002

Missing required parameters (tokenId or network)

20003

tokenId does not belong to the requesting partner

50002

Internal error (Sumsub client not configured or API failure)

Query Sumsub Status By Network

Endpoint: POST /v1/sumsub-status-by-network

Queries the current Sumsub KYC status for a specified tokenId on a given network. Returns the latest webhook status including review result and rejection details. Partners can only view records they created, or records with no partner association (legacy C-side data).

Prerequisites:

  • The partner must be whitelisted in Nacos (ur-other-sumsub-allowed-partners)

Request Parameters:

Field
Type
Required
Description

tokenId

string

Yes

UR NFT token ID on the target network

network

string

Yes

Chain ID (e.g., "5000" for Mantle, "42161" for Arbitrum)

Response Example:

Response Field Description:

  • type: Sumsub webhook type (e.g., applicantWorkflowCompleted, applicantReviewed)

  • reviewStatus: Review status (init, pending, completed, onHold)

  • reviewAnswer: Review result (GREEN for approved, RED for rejected)

  • reviewRejectType: Rejection type (only present when rejected, e.g., FINAL, RETRY)

  • levelName: Sumsub verification level name

  • rejectLabels: Array of rejection reason labels (only present when rejected)

  • applicantId: Sumsub applicant ID

  • applicantType: Applicant type (e.g., individual)

  • createdAtMs: Record creation timestamp in milliseconds

Error Codes:

Code
Description

10001

Partner not authenticated or not authorized

20002

Missing required parameters (tokenId or network)

50002

Internal error (query failed)

Notes:

  • If no record exists for the given tokenId + network, returns code=0 with an empty data object

  • The query is scoped to the requesting partner's data: records created by other partners are not visible

Apply USD Payin

Endpoint: POST /v1/apply-usd-payin

Initiate a USD Payin application for a specific URId and return an application ID. Once submitted, the operations team will review and approve the request. Upon approval, the user can proceed with the USD Payin operation.

Prerequisites:

  • Users must have performed at least one EUR or CHF Payin operation before they can submit the application.

Request Parameters:

Field
Type
Required
Description

urId

int64

Yes

UR NFT token ID

remark

string

Yes

Application Remark

Response Example:

Response Field Description:

  • applyId: Unique Application ID

Error Codes:

Code
Description

10001

Partner not authenticated or not authorized

30027

UrId already has an active USD Payin application

30028

User has not completed EUR or CHF Payin

50002

UR Internal error

Query CRS Task Status by TokenId

Endpoint: POST /v1/crs-status-by-token

Queries the current CRS Task status for a specified tokenId. Return whether a CRS task exists for the corresponding tokenId, along with the latest status of the CRS task.

Request Parameters:

Field
Type
Required
Description

tokenId

string

Yes

UR NFT token ID

Response Example:

Response Field Description:

  • needCrs: Whether the user is required to perform a CRS task

  • status: When the needCrs field is true, the status field indicates whether the user has submitted the CRS task: "submitted" means submitted, and "not_submitted" means not submitted.

  • url: The CRS submission link that directs the user to the CRS information collection page.

Error Codes:

PreviousKYC & complianceNextAPI reference: External Wallet Access

Last updated