> For the complete documentation index, see [llms.txt](https://docs.ur.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ur.app/api-reference/api/account/external-wallet-access-mode.md).

# External Wallet Access Mode

APIs signed by the user's own wallet key. Base URL <https://api.ur.app>.

## Get server timestamp

> Returns the current UR server timestamp. Use it to compute the signature deadline for Full Auth requests. No authentication required.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[],"paths":{"/api/v1/timestamp":{"get":{"tags":["External Wallet Access Mode"],"operationId":"ewaGetTimestamp","summary":"Get server timestamp","description":"Returns the current UR server timestamp. Use it to compute the signature deadline for Full Auth requests. No authentication required.","responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}},"components":{"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}}}
```

## Check email availability

> Checks whether an email address is available for registration. Returns retCode 10019 when the email is already registered. No authentication required.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[],"paths":{"/api/v2/email-status":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaCheckEmailStatus","summary":"Check email availability","description":"Checks whether an email address is available for registration. Returns retCode 10019 when the email is already registered. No authentication required.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Email address to check."}},"required":["email"]}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}},"components":{"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}}}
```

## Get user account status

> Returns the account status, KYC flow progress, Sumsub KYC info, novice guidance progress, and CRS requirements. Status codes: 0 Na, 1 SoftBlocked, 2 Tourist, 3 Blocked, 4 Closed, 5 Live.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[],"paths":{"/api/v2/account-status":{"get":{"tags":["External Wallet Access Mode"],"operationId":"ewaGetAccountStatus","summary":"Get user account status","description":"Returns the account status, KYC flow progress, Sumsub KYC info, novice guidance progress, and CRS requirements. Status codes: 0 Na, 1 SoftBlocked, 2 Tourist, 3 Blocked, 4 Closed, 5 Live.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."}],"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}},"components":{"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}}}
```

## Mint the user's URID

> Mints the URID NFT for a new user (account status must be Na). Requires GeeTest verification fields. The tokenId header carries the pre-generated URID.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[],"paths":{"/api/v1/mint":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaMintUrid","summary":"Mint the user's URID","description":"Mints the URID NFT for a new user (account status must be Na). Requires GeeTest verification fields. The tokenId header carries the pre-generated URID.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"User's Ethereum wallet address."},"lotNumber":{"type":"string","description":"GeeTest verification session ID."},"captchaOutput":{"type":"string","description":"GeeTest verification output result."},"passToken":{"type":"string","description":"GeeTest pass token."},"genTime":{"type":"string","description":"GeeTest generation timestamp (seconds)."},"image":{"type":"string","description":"NFT image (Base64). Optional."},"backGroundColor":{"type":"string","description":"Background color (hex). Optional."},"land":{"type":"string","description":"Land information. Optional."}},"required":["address","lotNumber","captchaOutput","passToken","genTime"]}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}},"components":{"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}}}
```

## Create a Sumsub SDK token

> Creates an access token to initialize the Sumsub SDK for KYC verification. The NFC scan step requires the Sumsub mobile SDK; it is not available in the web SDK. Omit userId unless UR gave you an explicit tenant pattern.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v1/sumsub/create-access-token":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaCreateSumsubAccessToken","summary":"Create a Sumsub SDK token","description":"Creates an access token to initialize the Sumsub SDK for KYC verification. The NFC scan step requires the Sumsub mobile SDK; it is not available in the web SDK. Omit userId unless UR gave you an explicit tenant pattern.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","description":"Optional. Server derives the Sumsub user id from Full Auth context when omitted."},"levelName":{"type":"string","description":"Specific Sumsub level name. Empty uses the default."},"ttl":{"type":"integer","description":"Token time-to-live in seconds. Default configured by the server."},"isRetryVerification":{"type":"boolean","description":"True for KYC retry scenarios."},"retryLevel":{"type":"integer","description":"Retry level (1-7); valid only when isRetryVerification is true."},"stepType":{"type":"string","description":"Specific verification step to reset, e.g. IDENTITY."},"failureReason":{"type":"string","description":"Failure reason, used for logging."}}}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Get Form A text

> Returns the Form A (customer due diligence) declaration text the user must read and sign after Sumsub verification. The user signs this exact text with their wallet.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v2/kyc/form-a-info":{"get":{"tags":["External Wallet Access Mode"],"operationId":"ewaGetFormAInfo","summary":"Get Form A text","description":"Returns the Form A (customer due diligence) declaration text the user must read and sign after Sumsub verification. The user signs this exact text with their wallet.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Submit signed Form A

> Submits the user's EIP-191 wallet signature over the exact Form A text from form-a-info. Completes the final KYC step. After success, allow about 3 seconds for downstream status updates.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v2/kyc/submit-form-a":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaSubmitFormA","summary":"Submit signed Form A","description":"Submits the user's EIP-191 wallet signature over the exact Form A text from form-a-info. Completes the final KYC step. After success, allow about 3 seconds for downstream status updates.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kycSelfDec":{"type":"string","description":"Form A text. Must exactly match the kycSelfDec returned by form-a-info."},"kycSelfDecSign":{"type":"string","description":"EIP-191 signature of the Form A text (65-byte hex, 0x prefix)."}},"required":["kycSelfDec","kycSelfDecSign"]}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Get user banking profile

> Returns the user's banking profile: IBAN, holder name, address, card eligibility, rolling 30-day CHF-denominated limits, payout contacts, and deposit bank details per currency. Verify outgoing amounts against limits.available before submitting.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v2/br":{"get":{"tags":["External Wallet Access Mode"],"operationId":"ewaGetProfile","summary":"Get user banking profile","description":"Returns the user's banking profile: IBAN, holder name, address, card eligibility, rolling 30-day CHF-denominated limits, payout contacts, and deposit bank details per currency. Verify outgoing amounts against limits.available before submitting.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Get card info

> Returns card metadata, limits, masked fields, and a short-lived cardToken (5 minute expiry) for rendering sensitive card details through UR's card display script. Do not store or log cardToken; use externalId for card management APIs.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v2/card":{"get":{"tags":["External Wallet Access Mode"],"operationId":"ewaGetCardInfo","summary":"Get card info","description":"Returns card metadata, limits, masked fields, and a short-lived cardToken (5 minute expiry) for rendering sensitive card details through UR's card display script. Do not store or log cardToken; use externalId for card management APIs.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Create card

> Applies for a new virtual card after KYC passes and card issuance conditions are met. Send an empty JSON body.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v2/card":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaCreateCard","summary":"Create card","description":"Applies for a new virtual card after KYC passes and card issuance conditions are met. Send an empty JSON body.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Set default transaction currency

> Sets the default transaction currency for the user's card. Use the stable externalId returned by Get card info as cardExternalId.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v2/card-currency":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaSetCardCurrency","summary":"Set default transaction currency","description":"Sets the default transaction currency for the user's card. Use the stable externalId returned by Get card info as cardExternalId.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cardExternalId":{"type":"string","description":"Stable card external ID from GET /api/v2/card (result.externalId)."},"currency":{"type":"string","description":"Default transaction currency, such as USD, EUR, or CHF."}},"required":["cardExternalId","currency"]}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Update card status

> Freezes (status 0) or unfreezes (status 1) the user's card. cardTokenId is the card's own token, not the user's URID.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v2/card-status":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaUpdateCardStatus","summary":"Update card status","description":"Freezes (status 0) or unfreezes (status 1) the user's card. cardTokenId is the card's own token, not the user's URID.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cardTokenId":{"type":"string","description":"The card's token (the card's specific ID, not the user's URID), retrieved from the cards interface."},"status":{"type":"integer","description":"Target status: 0 inactive (blocked), 1 active (unblocked)."}},"required":["cardTokenId","status"]}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Get transaction history

> Returns the user's transaction history with date range, type, currency, direction, and amount filters plus cursor pagination. Timestamps are Unix seconds.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v2/transactions":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaGetTransactions","summary":"Get transaction history","description":"Returns the user's transaction history with date range, type, currency, direction, and amount filters plus cursor pagination. Timestamps are Unix seconds.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pageSize":{"type":"integer","description":"Page size (default 50)."},"fromTimestamp":{"type":"integer","description":"Start timestamp (Unix seconds)."},"toTimestamp":{"type":"integer","description":"End timestamp (Unix seconds)."},"type":{"type":"string","description":"Single transaction type, e.g. P2P, FRX, CTU, CRD, CDP. Mutually exclusive with transactionTypes."},"transactionTypes":{"type":"array","items":{"type":"string"},"description":"Multiple transaction-type filter. Mutually exclusive with type."},"currencys":{"type":"array","items":{"type":"string"},"description":"Currency filter, e.g. EUR, USD, CHF."},"direction":{"type":"string","description":"IN, OUT, or ALL."},"minAmount":{"type":"string","description":"Minimum amount filter."},"maxAmount":{"type":"string","description":"Maximum amount filter."},"status":{"type":"string","description":"Transaction status filter."},"chainId":{"type":"string","description":"CAIP-2 chain ID, e.g. eip155:5000."},"tokenSymbol":{"type":"string","description":"Token symbol, e.g. USDC."},"cursorTimestamp":{"type":"integer","description":"Forward-pagination cursor timestamp."},"cursorId":{"type":"integer","description":"Forward-pagination cursor ID."},"id":{"type":"integer","description":"Query a single transaction by record ID. Mutually exclusive with txHash."},"txHash":{"type":"string","description":"Query a single transaction by hash. Mutually exclusive with id."}}}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Submit token permit

> Submits an EIP-2612 permit signature so UR contracts can spend tokens from the user's wallet without an on-chain approve transaction. Used for card spending against the user's UR fiat balance.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v1/token-permit":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaSubmitTokenPermit","summary":"Submit token permit","description":"Submits an EIP-2612 permit signature so UR contracts can spend tokens from the user's wallet without an on-chain approve transaction. Used for card spending against the user's UR fiat balance.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"Contract address of the token being approved."},"amount":{"type":"string","description":"Amount to approve (decimal string)."},"permitAmount":{"type":"string","description":"Permit amount signed in the EIP-2612 permit (decimal string)."},"permitDeadline":{"type":"integer","description":"Unix seconds until which the permit is valid."},"permitV":{"type":"integer","description":"EIP-2612 signature component v."},"permitR":{"type":"string","description":"EIP-2612 signature component r (32-byte hex)."},"permitS":{"type":"string","description":"EIP-2612 signature component s (32-byte hex)."}},"required":["address","amount","permitAmount","permitDeadline","permitV","permitR","permitS"]}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Get supported chain config

> Returns supported chains, token lists, contract addresses, and per-token Off-ramp and FX amount limits (minTopUpAmount, maxTopUpAmount, minFxAmount, maxFxAmount). Works logged in (adds balances and card eligibility) and logged out (config only). Read limits at request time; do not hardcode them.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[],"paths":{"/api/v3/config/chain-configs":{"get":{"tags":["External Wallet Access Mode"],"operationId":"ewaGetChainConfigs","summary":"Get supported chain config","description":"Returns supported chains, token lists, contract addresses, and per-token Off-ramp and FX amount limits (minTopUpAmount, maxTopUpAmount, minFxAmount, maxFxAmount). Works logged in (adds balances and card eligibility) and logged out (config only). Read limits at request time; do not hardcode them.","parameters":[{"name":"tokenId","in":"header","required":false,"schema":{"type":"string"},"description":"The user's URID. Omit for a non-logged-in query (config only, no balances)."},{"name":"network","in":"header","required":false,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":false,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":false,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":false,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}},"components":{"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}}}
```

## Get off-ramp quote (EVM)

> Returns the best aggregator quote for an EVM crypto deposit into fiat, including network and cross-chain fees. Quotes are cached for 60 seconds. Pass best.to, best.swapCalldata, and best.minUsdcAmount to the Off-ramp contract's depositTokenViaAggregator call.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[],"paths":{"/api/v1/partner/quote/deposit":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaGetOfframpQuote","summary":"Get off-ramp quote (EVM)","description":"Returns the best aggregator quote for an EVM crypto deposit into fiat, including network and cross-chain fees. Quotes are cached for 60 seconds. Pass best.to, best.swapCalldata, and best.minUsdcAmount to the Off-ramp contract's depositTokenViaAggregator call.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chainId":{"type":"string","description":"Source chain ID (CAIP-2), e.g. eip155:1."},"userAddress":{"type":"string","description":"User wallet address used to build the route."},"fromToken":{"type":"string","description":"Source token address. Use the zero address for native tokens."},"toToken":{"type":"string","description":"Target fiat token contract address."},"amount":{"type":"string","description":"Deposit amount in the token's smallest unit."}},"required":["chainId","userAddress","fromToken","toToken","amount"]}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}},"components":{"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}}}
```

## Get off-ramp quote (Solana)

> Returns execution parameters and a fiat-credit quote for a Solana USDC deposit, including an optional server-built unsigned VersionedTransaction. Partner-signed request on the partner API base URL. Validate the transaction structure before signing; production callers must pass network mainnet explicitly.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"DcEnvelope":{"type":"object","properties":{"code":{"type":"integer","description":"0 on success; non-zero indicates a business rejection.","format":"int64"},"message":{"type":"string","description":"Human-readable diagnostic; empty on success."},"data":{"description":"Business payload. Shape depends on the endpoint."}},"required":["code","message"],"description":"Standard response envelope for the partner API (openapi.ur.app)."}}},"paths":{"/v1/solana/deposit/quote":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaGetSolanaDepositQuote","summary":"Get off-ramp quote (Solana)","description":"Returns execution parameters and a fiat-credit quote for a Solana USDC deposit, including an optional server-built unsigned VersionedTransaction. Partner-signed request on the partner API base URL. Validate the transaction structure before signing; production callers must pass network mainnet explicitly.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"Partner's EIP-191 signature (0x-prefixed hex)."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when the request signature expires (within 5 minutes)."},{"name":"X-Api-PublicKey","in":"header","required":false,"schema":{"type":"string"},"description":"Partner's signer Ethereum address."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"urId":{"type":"integer","description":"User URID.","format":"int64"},"solanaAddress":{"type":"string","description":"User's Solana address (Base58); must match the transaction signing key."},"usdcAmount":{"type":"string","description":"Planned USDC input in smallest units (6 decimals). Minimum 5 USDC (\"5000000\")."},"outputCurrency":{"type":"string","description":"Target fiat currency code, e.g. USD."},"minUsdcAmount":{"type":"string","description":"Client-side slippage floor in smallest units. Omit or pass \"0\" for USDC-only deposits; the on-chain check runs after fee deduction."},"network":{"type":"string","description":"Solana cluster: mainnet for production, devnet for testing. Defaults to devnet when omitted."},"computeUnitPrice":{"type":"integer","description":"Solana priority fee in micro-lamports per compute unit. Server default 1000.","format":"int64"}},"required":["urId","solanaAddress","usdcAmount","outputCurrency"]}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DcEnvelope"}}}}}}}}}
```

## Get on-ramp limit

> On-ramp is not yet generally available; this endpoint is documented for preview only. Returns on-ramp eligibility signals and per-currency amount caps. Evaluate regionLocked, usdcDepegged, livenessLocked, maxAmounts, and minAmounts before starting the flow.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v1/onramp-limit":{"get":{"tags":["External Wallet Access Mode"],"operationId":"ewaGetOnrampLimit","summary":"Get on-ramp limit","description":"On-ramp is not yet generally available; this endpoint is documented for preview only. Returns on-ramp eligibility signals and per-currency amount caps. Evaluate regionLocked, usdcDepegged, livenessLocked, maxAmounts, and minAmounts before starting the flow.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## 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.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v1/quote/onramp":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaGetOnrampQuote","summary":"Get on-ramp quote","description":"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.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scene":{"type":"string","description":"onramp for the main flow; swap_retry for retrying a failed swap leg.","enum":["onramp","swap_retry"]},"srcChainId":{"type":"string","description":"Source chain ID (CAIP-2)."},"dstChainId":{"type":"string","description":"Destination chain ID (CAIP-2)."},"fromToken":{"type":"string","description":"Fiat token contract address."},"toToken":{"type":"string","description":"Destination token address."},"amount":{"type":"string","description":"Input amount in smallest units (e.g. \"10000\" is 100 USD)."},"slippageBps":{"type":"integer","description":"Slippage tolerance in basis points."}},"required":["scene","srcChainId","dstChainId","fromToken","toToken","amount"]}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Get liveness token

> Creates a Sumsub liveness access token for the on-ramp compliance flow. Call only when the on-ramp quote returns needLiveness true.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v2/get-liveness-token":{"get":{"tags":["External Wallet Access Mode"],"operationId":"ewaGetLivenessToken","summary":"Get liveness token","description":"Creates a Sumsub liveness access token for the on-ramp compliance flow. Call only when the on-ramp quote returns needLiveness true.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Check liveness result

> Polls the latest liveness status for the user in the on-ramp flow. Submit on-ramp only after liveness\_result is pass.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v2/check-liveness-result":{"get":{"tags":["External Wallet Access Mode"],"operationId":"ewaCheckLivenessResult","summary":"Check liveness result","description":"Polls the latest liveness status for the user in the on-ramp flow. Submit on-ramp only after liveness_result is pass.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Initiate on-ramp with permit

> On-ramp is not yet generally available; this endpoint is documented for preview only. Submits the on-ramp transaction with an EIP-2612 permit signature. Requires a valid cached quote (quoteId binding) and passed liveness when required; mismatched or expired quotes are rejected.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v1/onramp-with-permit":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaOnrampWithPermit","summary":"Initiate on-ramp with permit","description":"On-ramp is not yet generally available; this endpoint is documented for preview only. Submits the on-ramp transaction with an EIP-2612 permit signature. Requires a valid cached quote (quoteId binding) and passed liveness when required; mismatched or expired quotes are rejected.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quoteId":{"type":"string","description":"quoteId from the on-ramp quote."},"chainId":{"type":"string","description":"Source chain ID (CAIP-2)."},"tokenIn":{"type":"string","description":"Fiat token contract address."},"amountIn":{"type":"string","description":"Input amount in smallest units; must match the cached quote."},"dstChainId":{"type":"string","description":"Destination chain ID (CAIP-2)."},"dstAggregator":{"type":"string","description":"best.to from the quote."},"dstTokenOut":{"type":"string","description":"Destination token address."},"dstSwapCalldata":{"type":"string","description":"best.swapCalldata from the quote."},"dstMinAmountOut":{"type":"string","description":"best.minAmountOut from the quote."},"permitDeadline":{"type":"integer","description":"Unix seconds until which the permit is valid."},"permitV":{"type":"integer","description":"EIP-2612 signature component v."},"permitR":{"type":"string","description":"EIP-2612 signature component r."},"permitS":{"type":"string","description":"EIP-2612 signature component s."}},"required":["quoteId","chainId","tokenIn","amountIn","permitDeadline","permitV","permitR","permitS"]}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Check pending on-ramp retry

> Returns one pending on-ramp retry candidate when a previous destination swap failed, or a null result when none exists. Poll periodically; the user can retry the swap or cancel.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v1/onramp/pending-retry":{"get":{"tags":["External Wallet Access Mode"],"operationId":"ewaGetOnrampPendingRetry","summary":"Check pending on-ramp retry","description":"Returns one pending on-ramp retry candidate when a previous destination swap failed, or a null result when none exists. Poll periodically; the user can retry the swap or cancel.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Retry on-ramp swap with permit

> Executes the destination-chain swap retry for a failed on-ramp. Requires a fresh quote with scene swap\_retry; request fields must match the quote cache and the original retry record.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v1/onramp-swap-with-permit":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaOnrampSwapWithPermit","summary":"Retry on-ramp swap with permit","description":"Executes the destination-chain swap retry for a failed on-ramp. Requires a fresh quote with scene swap_retry; request fields must match the quote cache and the original retry record.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quoteId":{"type":"string","description":"quoteId from a fresh quote with scene swap_retry."},"chainId":{"type":"string","description":"Destination chain ID (CAIP-2), from the pending retry."},"originalTxHash":{"type":"string","description":"Original on-ramp transaction hash, from the pending retry."},"usdcAmount":{"type":"string","description":"Stuck USDC amount in smallest units."},"tokenOut":{"type":"string","description":"Destination token address."},"minAmountOut":{"type":"string","description":"best.minAmountOut from the retry quote."},"aggregator":{"type":"string","description":"best.to from the retry quote."},"swapCalldata":{"type":"string","description":"best.swapCalldata from the retry quote."},"permitDeadline":{"type":"integer","description":"Unix seconds until which the permit is valid."},"permitV":{"type":"integer","description":"EIP-2612 signature component v."},"permitR":{"type":"string","description":"EIP-2612 signature component r."},"permitS":{"type":"string","description":"EIP-2612 signature component s."}},"required":["quoteId","chainId","originalTxHash","usdcAmount","tokenOut","minAmountOut","aggregator","swapCalldata","permitDeadline","permitV","permitR","permitS"]}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Cancel on-ramp retry

> Cancels a pending on-ramp retry when the user explicitly abandons it. Use only when a retry-eligible transaction exists.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v1/onramp/retry/cancel":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaCancelOnrampRetry","summary":"Cancel on-ramp retry","description":"Cancels a pending on-ramp retry when the user explicitly abandons it. Use only when a retry-eligible transaction exists.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"originalTxHash":{"type":"string","description":"Original on-ramp transaction hash of the pending retry."}},"required":["originalTxHash"]}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Verify payment reference

> Validates user-entered payment reference text for a bank transfer and returns purposeId and refId for the payout submission.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v1/verify-reference":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaVerifyReference","summary":"Verify payment reference","description":"Validates user-entered payment reference text for a bank transfer and returns purposeId and refId for the payout submission.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","description":"The payment reference to validate."}},"required":["reference"]}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Verify contact

> Validates the final recipient and bank payload for a bank transfer and returns contactId, purposeId, and refId. Creditor name, street, city, and country should use Latin characters.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v1/verify-contact":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaVerifyContact","summary":"Verify contact","description":"Validates the final recipient and bank payload for a bank transfer and returns contactId, purposeId, and refId. Creditor name, street, city, and country should use Latin characters.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"string","description":"Recipient IBAN or account number."},"bankName":{"type":"string","description":"Recipient bank name."},"bic":{"type":"string","description":"Recipient bank BIC."},"purpose":{"type":"integer","description":"Payment purpose ID from the payment purposes list."},"reference":{"type":"string","description":"Payment reference."},"creditor":{"type":"object","properties":{"name":{"type":"string"},"street":{"type":"string"},"city":{"type":"string"},"zip":{"type":"string"},"country":{"type":"string"}},"description":"Recipient details. Latin characters required."}},"required":["account","bankName","bic","purpose","reference"]}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Create payout with permit

> Creates a bank payout with an EIP-2612 permit signature and submits it on-chain. Recipient fields must use Latin characters; the network fee is deducted from the transfer amount. Payouts count against the user's rolling 30-day limit.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v1/payout-with-permit":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaPayoutWithPermit","summary":"Create payout with permit","description":"Creates a bank payout with an EIP-2612 permit signature and submits it on-chain. Recipient fields must use Latin characters; the network fee is deducted from the transfer amount. Payouts count against the user's rolling 30-day limit.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"Payout amount in smallest units."},"permitAmount":{"type":"string","description":"Permit amount signed in the EIP-2612 permit."},"permitDeadline":{"type":"integer","description":"Unix seconds until which the permit is valid."},"permitV":{"type":"integer","description":"EIP-2612 signature component v."},"permitR":{"type":"string","description":"EIP-2612 signature component r."},"permitS":{"type":"string","description":"EIP-2612 signature component s."},"contactId":{"type":"string","description":"Contact ID from the profile contacts or verify-contact."},"tokenAddress":{"type":"string","description":"Fiat token contract address to pay out from."},"purposeId":{"type":"string","description":"Payment purpose ID from verify-reference or verify-contact."},"ref":{"type":"string","description":"Reference ID from verify-reference or verify-contact."},"metadata":{"type":"object","properties":{"bankAccountHolder":{"type":"string"},"bankName":{"type":"string"},"bankAccount":{"type":"string"},"bankReference":{"type":"string"}},"description":"Recipient bank details. Latin characters required."}},"required":["amount","permitAmount","permitDeadline","permitV","permitR","permitS","contactId","tokenAddress"]}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```

## Get FX quote

> Returns the quoted FX output amount (smallest units) and exchange rate for a fiat token pair. Quote mode is exact\_in. Read per-token FX limits from the chain config; do not hardcode them.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[],"paths":{"/api/v1/quote/fx":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaGetFxQuote","summary":"Get FX quote","description":"Returns the quoted FX output amount (smallest units) and exchange rate for a fiat token pair. Quote mode is exact_in. Read per-token FX limits from the chain config; do not hardcode them.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputAmount":{"type":"string","description":"Input amount in smallest units."},"inputToken":{"type":"string","description":"Input fiat token contract address."},"outputToken":{"type":"string","description":"Output fiat token contract address."}},"required":["inputAmount","inputToken","outputToken"]}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}},"components":{"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}}}
```

## Execute FX with permit

> Executes an on-chain FX exchange using an EIP-2612 permit signature. Derive amountOutMinimum from the FX quote; permitValue must be at least inputAmount. Final status is trackable via txHash.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"External Wallet Access Mode","description":"APIs signed by the user's own wallet key. Base URL https://api.ur.app."}],"servers":[{"url":"https://api.ur.app","description":"Production (user API)"},{"url":"https://urapi3-qa.ur-inc.xyz","description":"Testnet (user API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"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."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}},"paths":{"/api/v1/fx-exchange-with-permit":{"post":{"tags":["External Wallet Access Mode"],"operationId":"ewaFxExchangeWithPermit","summary":"Execute FX with permit","description":"Executes an on-chain FX exchange using an EIP-2612 permit signature. Derive amountOutMinimum from the FX quote; permitValue must be at least inputAmount. Final status is trackable via txHash.","parameters":[{"name":"tokenId","in":"header","required":true,"schema":{"type":"string"},"description":"The user's URID (NFT token id)."},{"name":"network","in":"header","required":true,"schema":{"type":"string"},"description":"Network identifier: 5000 for mainnet, 5003 for testnet."},{"name":"sign","in":"header","required":true,"schema":{"type":"string"},"description":"Signature generated by the user's wallet key (EIP-191)."},{"name":"hash","in":"header","required":true,"schema":{"type":"string"},"description":"SHA3/Keccak256 hash of the original request payload."},{"name":"deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Signature expiry: server timestamp plus a validity window (max 20 minutes)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userAddress":{"type":"string","description":"User's wallet address."},"inputToken":{"type":"string","description":"Input fiat token contract address."},"outputToken":{"type":"string","description":"Output fiat token contract address."},"inputAmount":{"type":"string","description":"Exact-in amount in smallest units."},"amountOutMinimum":{"type":"string","description":"Minimum acceptable output in smallest units, from the quote."},"permitValue":{"type":"string","description":"Permit value; must be greater than or equal to inputAmount."},"permitDeadline":{"type":"integer","description":"Unix seconds until which the permit is valid."},"permitV":{"type":"integer","description":"EIP-2612 signature component v."},"permitR":{"type":"string","description":"EIP-2612 signature component r (32-byte hex)."},"permitS":{"type":"string","description":"EIP-2612 signature component s (32-byte hex)."}},"required":["userAddress","inputToken","outputToken","inputAmount","amountOutMinimum","permitValue","permitDeadline","permitV","permitR","permitS"]}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EwaEnvelope"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ur.app/api-reference/api/account/external-wallet-access-mode.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.