---
title: "Prepare account registration"
method: POST
path: "/setup-account"
tags: ["Accounts"]
---

# Prepare account registration

`POST /setup-account`

## Request

- Base URL: `https://v1.orchestrator.rhinestone.dev/deposit-processor`
- URL: `https://v1.orchestrator.rhinestone.dev/deposit-processor/setup-account`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/rhinestonewtf/apis/deposit-service-api/docs/setup-account/post.ts> (a function with typed inputs; its response is checked against the schema)

Returns a deposit address or the details needed to register the account. Existing account ownership, kind, and destination are immutable; a conflicting request is refused before session details are created.

## Headers

- `x-api-key` string: API key for authentication
- `x-api-version` string: API version identifier (e.g. "2026-04.amazon"). Optional today, will become required in a future release.

## Request body

- SetupAccountRequestBody: Preflight for registration. Address owner, kind and destination are immutable; destination changes require a new address. Explicitly supplied scopes on existing chains require a new signature and replace stored scopes; omission preserves them. Replacement does not revoke older on-chain sessions.
  - `ownerAddress` string, required: Ethereum address (0x followed by 40 hex characters)
  - `sessionOwnerAddress` string, required: Ethereum address (0x followed by 40 hex characters)
  - `targetToken` string, required
  - `targetChain` string, required: CAIP-2 chain identifier (e.g. "eip155:8453")
  - `recipient` string: Address that receives the final tokens. Must not be a placeholder, burn or chain system address: the zero address, an address of one repeated hex digit (0x1111…, incl. HyperCore HYPE 0x2222…), 0x…dEaD, or a HyperCore token system address (0x20 followed by zeros and the token index). Such values are rejected with 400.
  - `outputTokenRules` OutputTokenRule[]
    - `match` OutputTokenRuleMatch, required: Source-token match criteria. Rules may match by source chain, source token address, source symbol, or a combination.
      - `chain` string: CAIP-2 chain identifier (e.g. "eip155:8453")
      - `token` string
      - `symbol` string
    - `outputToken` string, required
  - `rejectUnmapped` boolean
  - `postBridgeActions` unknown
  - `sessionScopes` SessionScopes
  - `signerAddress` string: Ethereum address (0x followed by 40 hex characters)
  - `sessionChainIds` integer[]
  - `forceRegister` boolean

## Response `200`

Account setup result

- SetupAccountResponse
  - `smartAccount` string, required: Ethereum address (0x followed by 40 hex characters)
  - `isRegistered` boolean, required
  - `targetChain` string
  - `targetToken` string
  - `needsRegistration` boolean, required
  - `solanaDepositAddress` string
  - `accountParams` object
    - `factory` string, required: Ethereum address (0x followed by 40 hex characters)
    - `factoryData` string, required: Hex-encoded string (0x followed by hex characters)
    - `sessionScopes` SessionScopes
  - `sessionDetailsUnsigned` object
    - `hashesAndChainIds` object[], required
      - `chainId` string, required
      - `sessionDigest` string, required: Hex-encoded string (0x followed by hex characters)
    - `data` object, required

## Other responses

- `400`: Invalid request or unauthorized
- `401`: Authentication required or the presented credential is invalid.
- `403`: API key lacks required deposits scope, or user-owned accounts are not enabled for the organization (`USER_OWNED_ACCOUNTS_NOT_ENABLED`; use `POST /register-managed`)
- `409`: The derived address is already registered to a different project, account kind, or destination. Use a new address for a new destination.
- `500`: Failed to derive account or build sessions
- `503`: Could not verify the existing mapping; retry shortly

## Changes

- **2026-11-06** `aa1767d704fa`: 4 info
  - the endpoint scheme security `internalProjectBearer` was added to the API
  - the endpoint scheme security `tenantApiKey` was added to the API
  - the `header` request parameter `x-api-key` became optional
  - added the non-success response with the status `401`
- **2026-09-30** `a6fd693c3d5f`: 2 info
  - added the non-success response with the status `409`
  - added the non-success response with the status `503`
- **2026-09-17** `676300ac19ff`: 3 info
  - added the optional property `code` to the response with the `400` status
  - added the optional property `code` to the response with the `403` status
  - added the optional property `code` to the response with the `500` status
- **2026-09-11** `b49146029e5a`: 2 info
  - added the new optional request property `sessionScopes`
  - added the optional property `accountParams/sessionScopes` to the response with the `200` status
- **2026-09-04** `54262a43c6a8`: 2 breaking
  - request property `targetChain` list-of-types was narrowed by removing types `integer` from media type `application/json`
  - added the pattern `^[a-z0-9]+:[a-zA-Z0-9]+$` to the request property `targetChain`

[Operation history](https://skmtc.dev/rhinestonewtf/apis/deposit-service-api/changes/setup-account/post.md)

---

[API](https://skmtc.dev/rhinestonewtf/apis/deposit-service-api.md) - [All operations](https://skmtc.dev/rhinestonewtf/apis/deposit-service-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rhinestonewtf/apis/deposit-service-api/revisions/aa1767d704fa?raw)