# Integration overview (/docs/tokenization/integration)



## Three kinds of interaction [#three-kinds-of-interaction]

Applications work with the platform API, indexed chain data, and wallet-signed transactions. Each serves a different purpose; treating all three as a single synchronous operation can produce misleading status displays.

| Layer                     | Responsibility                                                                                |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| Platform services         | Sessions, organization access, verification workflows, claims orchestration, and durable jobs |
| Indexer and read services | Searchable projections of balances, transfers, identities, claims, and asset records          |
| Contracts and wallets     | Enforce on-chain permissions and rules, authorize transactions, and record execution          |

## Authentication and authority [#authentication-and-authority]

The portals use [Sign-In with Ethereum](/docs/resources/glossary#siwe) to establish wallet-associated sessions. Workspace membership controls platform actions, while contract roles control on-chain actions. Existing [Safe](/docs/resources/glossary#safe) accounts introduce threshold approvals and scoped owner or delegate access.

An application should show which account and wallet are acting, and distinguish preparing an operation from authorizing it. A valid session is not blanket transaction authority.

## Transaction and job state [#transaction-and-job-state]

Some platform operations create durable jobs, such as issuer registration, claims issuance, or suite deployment. Others ask an issuer or investor wallet to sign directly. Safe actions may wait for multiple approvals before execution.

Present the relevant stages explicitly: requested, awaiting authorization, submitted, confirmed, and reflected in indexed data. A queued job is not a confirmed transaction. A transaction receipt also does not guarantee that an indexed portfolio has already refreshed.

Reusing an existing request or its supported retry path is preferable to blindly creating a duplicate. Some failures require operator recovery, especially when the outcome of a submitted transaction is uncertain.

## Read models and preliminary checks [#read-models-and-preliminary-checks]

The platform normally reads chain-derived data through its indexer. This makes queries efficient but introduces a delay between execution and display. Integrations should communicate freshness and pending updates.

Transfer [preflight](/docs/resources/glossary#preflight) explains likely refusals using current information. The contracts remain authoritative when the transaction executes. A successful preliminary check cannot guarantee that balances, claims, or rules remain unchanged until submission.

## Environment boundaries [#environment-boundaries]

Resolve network and contract configuration for the intended environment. Token addresses, available market features, onboarding policy, and payment assets are deployment-specific. Testnet self-service access does not imply production admission or Business Validator permission.

## Discover testnet configuration [#discover-testnet-configuration]

The portal platform exposes public configuration at:

```text
GET https://testnet.rwa-platform.real.finance/v1/config
```

It returned HTTP 200 without authentication on **17 September 2026**. Relevant fields from that observation:

```json
{
  "network": "testnet",
  "chainId": 117711,
  "features": {
    "escrowDvpEnabled": true,
    "secondaryMarketEnabled": true,
    "issuerOnboardingEnabled": true,
    "automaticTokenDeployment": true
  },
  "navStalenessDays": 1
}
```

This is an excerpt. The response also includes `rpcUrl`, `explorerUrl`, contract `addresses`, and claim `topics`. Feature flags describe the responding service; they do not prove every asset supports a feature or that a production audit gate has been met.

## Read and authenticate at the right service [#read-and-authenticate-at-the-right-service]

| Request                        | Access                             | Result                                                          |
| ------------------------------ | ---------------------------------- | --------------------------------------------------------------- |
| `GET /v1/config`               | Public                             | Deployment configuration and feature flags                      |
| `GET /v1/assets?limit=1`       | Public, rate-limited               | Listed assets in `data`, with `pagination` and freshness `meta` |
| `GET /v1/assets/:token`        | Public, rate-limited               | One listed asset and its documents                              |
| `GET /v1/portfolio`            | Wallet session                     | Account-scoped positions and freshness information              |
| `POST /v1/transfers/preflight` | Wallet session and CSRF protection | Preliminary transfer checks; no transfer submission             |

These routes belong to `testnet.rwa-platform.real.finance`. They are not interchangeable with the network/protocol API at `testnet.api.real.finance/v1` or separate indexer APIs. Do not send an API key and assume it establishes a portal wallet session. The portal authentication flow uses Sign-In with Ethereum, scoped sessions, and CSRF protection for mutations.

Handle HTTP failures before parsing success data. Protected routes can reject missing sessions or insufficient permissions; rate limits can return 429. An unlisted or unknown asset can return 404. Preserve returned application error codes, such as `nav_stale`, rather than treating every 409 as a reason to repeat an action.

Use [Build an application](/docs/chain/build) for a complete viem read and contract simulation. The contract simulation is distinct from the account-scoped platform preflight above.

## Testnet services [#testnet-services]

The [tokenization API](https://testnet.rwa-platform.real.finance) provides the platform entry point. Check [API readiness](https://testnet.rwa-platform.real.finance/v1/health/ready) and [indexer health](https://testnet.rwa-ponder.real.finance/health) separately: a responsive API does not by itself prove its indexed view is current. The [network endpoint directory](/docs/chain/networks#developer-endpoints) also lists chain and protocol services.