Integration guide

1 Let people sign in

Register the exact callback URL in Applications Use the authorization code flow with PKCE S256 Keep a random state value in the user session and verify it on return Exchange the single use code on the token endpoint Confidential clients keep their secret on their server

Request only the scopes you need: identity:read for identity details, spaces:write for asset operations, and coins:transfer for payments Users can revoke access in Security Tokens do not let your app sign wallet transactions To request user approval without handling their keys, call POST /v1/wallet-requests with the same body as prepare Open the returned approval_path on xityconnect.com The user reviews and signs there Poll GET /v1/wallet-requests/request_id with the original OAuth token for the submitted transaction or a decline Requests expire in five minutes and revoked connections cannot proceed

2 Create assets through your app

Before the first launch, send the user to /identity/apply?purpose=creator for identity verification and operator approval, check /identity/launch-status from their signed in Xity account After approval, call POST /v1/transactions/prepare with app_id, tx_type and payload Minting uses SPACE_MINT Its payload includes your own wallet address in to, your app_id, metadata_uri and a version 2 royalty_policy For a 5% creator royalty and 1% per previous buyer, set creator_bps to 500 and buyer_bps to 100 For individual buyer rates, use buyer_schedule_bps such as 100 followed by 50, and set buyer_bps to 0

The prepared transaction contains the exact nonce, timestamp and network Show the user its contents Verify the signing bytes against that transaction, sign those bytes with the user wallet, then submit the unchanged transaction with its hex Ed25519 signature to POST /v1/transactions/submit

App code can use the downloadable HTTP client in a browser or Node Your wallet adapter must provide explicit approval and signing Never ask users to paste their private key into your website Never store a private signing key in public app configuration

Keep your application data connected

Create a namespace from your application workspace Save versioned records with APP_RECORD_PUT, remove them with APP_RECORD_DELETE, or apply up to 32 changes atomically with APP_RECORD_BATCH Set space_id to reference a Space NFT created by the same application Private namespaces accept encrypted envelopes only User areas let a connected wallet write within its own users/address/ prefix after consent and a separate wallet signature

3 Bring any kind of asset

Upload a file with POST /v1/media?app_id=your_app using raw bytes and a Bearer session or spaces:write token, then create immutable metadata with POST /v1/metadata The JavaScript client provides uploadMedia and createMetadata Use the returned metadata_uri and metadata_hash in the mint payload Xity hosts the bytes on its own infrastructure, the chain stores the address and fingerprint, the workspace shows the actual media preview Images can be up to 12 MB and other files up to 32 MB, each account has a 256 MB media allowance

External HTTPS, IPFS and Arweave metadata remain supported, publish JSON with name, description, image or animation_url and optional attributes The backend resolves previews with public network checks and bounded downloads, it does not execute asset content Use SPACE_UPDATE_METADATA to update an address and optional metadata_hash as the original creator Previous values remain in the chain history Do not store unencrypted personal information or secrets on the chain

4 Open a marketplace

The creator opens transfers with SPACE_OPEN_TRANSFERS A holder signs SPACE_LIST with space_id and an integer price A buyer reads the listing and royalty quote, then signs SPACE_BUY with space_id and listing_id Payment, royalty distribution and ownership change are atomic A changed listing requires a new review SPACE_CANCEL_LISTING removes a listing SPACE_TRANSFER sends a gift without payment and does not earn a new buyer royalty

Royalties across the creator and previous buyers have a combined 15% maximum New buyer shares use the remaining capacity, then stop at the cap A separate 3% platform fee applies All API amounts are integer cents 100 cents equals 1 XityCoin Display amounts in XityCoin to your users No bank funding is currently connected Do not describe a balance as verified SGD reserves

5 Handle confirmation and recovery

Save tx_id before navigating away Query GET /v1/transactions/tx_id until status is confirmed, then retain its block hash and height Applied means the change is awaiting a block A timeout does not prove failure Resubmit the same signed transaction to retry safely Do not create a new payment until the first status is known

401 means sign in again 403 means the app lacks consent or a signature is invalid 409 means state changed, such as a nonce or listing conflict Read the current state and ask the user to review a new transaction Confirmation expires after five minutes

Use a name instead of a long address

GET /v1/accounts/resolve?identifier=value accepts account names, short Xity IDs and full addresses, the JavaScript client exposes resolveAccount Resolve before preparing a payment or gift, display the resolved account to the user and sign the returned canonical wallet address, do not shorten or replace addresses inside signatures or saved records

OAuth user information includes short_id and account_name alongside the unchanged address, keep the address as your stable account key Personal account QRs and connection QRs use opaque Xity payloads, they never contain passwords or signing keys

Architecture options

Use Xity only for sign in, assets or payments while keeping your existing database Or store public asset ownership and marketplace settlement on Xity while serving the rest from your app The API provides native chain operations It does not run arbitrary uploaded application code

API base

https://api.xityconnect.org

Capabilities

GET /v1/capabilities

Public assets

GET /v1/spaces

Quote

GET /v1/spaces/space_id/quote?sale_price=integer

AI discovery

Plain text integration reference