> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rialto.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrator Onboarding

> Create an integrator profile and API key through the wallet-signed onboarding flow.

## Overview

Integrator keys are created through a wallet-signed onboarding flow. The wallet
that applies becomes the owner wallet for the integrator profile and must also be
the fee-recipient wallet.

The flow is:

1. Build the application payload and its payload\_hash.
2. Call POST /integrators/nonce with action create\_integrator\_application.
3. Sign the exact message returned by the nonce endpoint with the owner wallet.
4. Submit the signed application to POST /integrators/applications.
5. Wait for Rialto approval if the application returns status: "pending".
6. After approval, request another nonce for create\_integrator\_api\_key, sign it,
   and call POST /integrators/api-keys.
7. Store the returned api\_key immediately. It is shown once. Later profile reads
   only return a masked key.

## Payload hash format

Mutable integrator actions require a payload\_hash:

```text theme={null}
keccak256("field_name=<byte length>:<value>\n" for each field, in order)
```

Use UTF-8 byte length for each value. Optional fields are encoded as `none` or
`some:<value>`.

## Endpoint: create integrator nonce

```http theme={null}
POST /integrators/nonce
```

Auth: public.

| Field         | Description                                                                                                                       |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| chain\_id     | Optional chain id. Use 4663 for Robinhood Chain.                                                                                  |
| wallet        | Owner wallet that will sign.                                                                                                      |
| action        | One of create\_integrator\_application, create\_integrator\_api\_key, revoke\_integrator\_api\_key, or view\_integrator\_profile. |
| payload\_hash | Required for create and revoke actions. Not required for view\_integrator\_profile.                                               |

Response includes message, nonce, issued\_at, and expiration\_time. Sign the exact
message string. Do not reconstruct it client-side.

## Endpoint: submit application

```http theme={null}
POST /integrators/applications
```

Auth: public.

| Field                                          | Description                                                                   |
| ---------------------------------------------- | ----------------------------------------------------------------------------- |
| chain\_id                                      | Optional chain id.                                                            |
| owner\_wallet                                  | Wallet that owns the integrator profile.                                      |
| display\_name                                  | Human-readable partner or app name.                                           |
| slug                                           | Lowercase unique id, 3-64 chars, lowercase letters, digits, and hyphens only. |
| contact\_email                                 | Optional.                                                                     |
| telegram\_handle                               | Optional.                                                                     |
| app\_url                                       | Optional.                                                                     |
| fee\_recipient                                 | Wallet that receives integrator fees. Must equal owner\_wallet.               |
| requested\_max\_fee\_bps                       | Max fee cap requested for this key, in basis points.                          |
| payload\_hash                                  | Hash of the application fields.                                               |
| nonce, issued\_at, expiration\_time, signature | Fields from /integrators/nonce plus the wallet signature.                     |

Example response:

```json theme={null}
{
  "integrator_id": 12,
  "slug": "example-wallet",
  "status": "pending",
  "message": "Application submitted for review."
}
```

If status is pending, the Rialto team will review your application. If approved,
the profile status becomes active and you can create an API key for it. If the
application response already returns active, you can create a key immediately.

## Endpoint: create API key

```http theme={null}
POST /integrators/api-keys
```

Auth: public.

| Field                                          | Description                                                          |
| ---------------------------------------------- | -------------------------------------------------------------------- |
| chain\_id                                      | Optional chain id.                                                   |
| owner\_wallet                                  | Integrator owner wallet.                                             |
| integrator\_id                                 | Numeric id returned by the application endpoint.                     |
| label                                          | Human-readable key label.                                            |
| payload\_hash                                  | Hash of action, chain\_id, owner\_wallet, integrator\_id, and label. |
| nonce, issued\_at, expiration\_time, signature | Fields from /integrators/nonce plus the wallet signature.            |

Response:

```json theme={null}
{
  "key_id": 34,
  "api_key": "rialto_live_example.redacted_secret",
  "masked_key": "rialto_live_example...cret",
  "prefix": "example",
  "scopes": ["quote:read", "swap:create", "swap:integrator"],
  "quote_rate_limit_per_minute": 60,
  "swap_rate_limit_per_minute": 10,
  "integrator_id": "example-wallet",
  "integrator_fee_recipient": "<taker_wallet_address>",
  "integrator_max_fee_bps": 50,
  "shown_once": true
}
```

The api\_key is shown only once at creation. Store it securely when this response
is returned. It cannot be retrieved again; /integrators/me only returns masked key
metadata.

## Profile and key management

| Endpoint                                   | Purpose                                                       |
| ------------------------------------------ | ------------------------------------------------------------- |
| POST /integrators/me                       | List profiles and masked keys for an owner wallet.            |
| POST /integrators/api-keys/{key_id}/revoke | Revoke a key. Revoked keys are rejected by trading endpoints. |

Use action view\_integrator\_profile on /integrators/nonce, sign the returned
message, then submit owner\_wallet, nonce fields, and signature to /integrators/me.
Use action revoke\_integrator\_api\_key to revoke a key. Compute the payload\_hash
from owner\_wallet, integrator\_id, and key\_id.

A full runnable Python example for application and key creation is in the API
repo:
[https://github.com/rialto-plds/rialto-api-docs/blob/main/RIALTO\_SWAP\_API.md](https://github.com/rialto-plds/rialto-api-docs/blob/main/RIALTO_SWAP_API.md)