Skip to main content

​
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: 
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

POST /integrators/nonce
Auth: public.
FieldDescription
chain_idOptional chain id. Use 4663 for Robinhood Chain.
walletOwner wallet that will sign.
actionOne of create_integrator_application, create_integrator_api_key, revoke_integrator_api_key, or view_integrator_profile.
payload_hashRequired 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

POST /integrators/applications
Auth: public.
FieldDescription
chain_idOptional chain id.
owner_walletWallet that owns the integrator profile.
display_nameHuman-readable partner or app name.
slugLowercase unique id, 3-64 chars, lowercase letters, digits, and hyphens only.
contact_emailOptional.
telegram_handleOptional.
app_urlOptional.
fee_recipientWallet that receives integrator fees. Must equal owner_wallet.
requested_max_fee_bpsMax fee cap requested for this key, in basis points.
payload_hashHash of the application fields.
nonce, issued_at, expiration_time, signatureFields from /integrators/nonce plus the wallet signature.
Example response: 
{
  "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

POST /integrators/api-keys
Auth: public.
FieldDescription
chain_idOptional chain id.
owner_walletIntegrator owner wallet.
integrator_idNumeric id returned by the application endpoint.
labelHuman-readable key label.
payload_hashHash of action, chain_id, owner_wallet, integrator_id, and label.
nonce, issued_at, expiration_time, signatureFields from /integrators/nonce plus the wallet signature.
Response: 
{
  "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

EndpointPurpose
POST /integrators/meList profiles and masked keys for an owner wallet.
POST /integrators/api-keys//revokeRevoke 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