> ## Documentation Index > Fetch the complete documentation index at: https://docs.stableyard.fi/llms.txt > Use this file to discover all available pages before exploring further. # Set an account's settlement preference > Choose which active destination a UPA's incoming money settles to. Pass a `settlementDestinationId` returned by [List an account's settlement destinations](/api-reference/settlement/list-settlement-destinations), and optionally an `assetSymbol`. The destination must be active: crypto destinations resolve to their linked wallet, and unverified bank and rail destinations fail closed. Repeating the same preference returns the existing profile. Deposits and Payments that already exist keep their immutable settlement snapshot. See [Settlement destinations](/settlement/destinations). ## OpenAPI ````yaml openapi.json PUT /v2/accounts/{accountId}/settlement-profile openapi: 3.1.0 info: title: Stableyard Partner API version: 2.0.0-staging x-stableyard-api-version: '2026-09-09' x-stableyard-supported-api-versions: - '2026-09-09' summary: Backend API for UPAs, Payments, activity, and optional financial products. description: > Use this API from a trusted partner backend with an app ID and app secret. ## Recommended integration 1. Call `GET /v2/partners/config` to verify credentials and discover enabled capabilities. 2. Create a UPA only when your product needs a persistent Stableyard account. 3. Create a receive or send Payment with `POST /v2/payments`. 4. Redirect a payer to the returned `paymentUrl` or pass the Payment credentials to an official Stableyard interface SDK. 5. Process signed webhooks and fetch the Payment by ID for reconciliation. Checkout execution and account-bound browser endpoints are intentionally documented in the separate Interfaces & SDKs reference. Console endpoints are dashboard implementation details and are not part of the partner integration contract. x-stableyard-documentation-surface: partner servers: - url: https://prod-api.stableyard.fi description: Production - url: https://staging-api-v2.stableyard.fi description: Staging - url: http://localhost:3001 description: Local security: [] tags: - name: Authentication x-displayName: API authentication description: Verify your app ID and app secret before calling UPA APIs. - name: Accounts x-displayName: UPA Accounts description: Create Universal Payment Accounts and manage account settings. - name: Deposit Addresses description: Create reusable receive addresses and verify inbound deposits. - name: Identity & KYC description: >- Verify the UPA email and run provider-neutral identity verification. Managed vaults and fiat payment rails use this same verified UPA identity. - name: Vaults description: >- Create Safe/Zodiac controlled stablecoin vaults and manage policy updates for accounts. - name: Payments description: >- Create escrow-first payments, issue partner-authenticated send instructions or executions, power public checkout, and reconcile collection through final account settlement. - name: Balances & Transactions description: >- Read Stableyard-posted financial activity. Balances are ledger projections of activity Stableyard processed; they are not live balances of externally controlled wallets. paths: /v2/accounts/{accountId}/settlement-profile: put: tags: - Accounts summary: Set account settlement preference description: >- Choose an active typed settlement destination returned by `GET /v2/accounts/{accountId}/settlement-destinations`. Crypto destinations resolve to their linked wallet. Unverified bank and rail destinations fail closed. Repeating the same preference returns the existing profile. Existing deposits and Payments keep their immutable snapshot. operationId: setSettlementProfileByAccountId parameters: - name: accountId in: path required: true schema: type: string example: acct_123 description: Canonical account id returned by the Accounts API. - name: Stableyard-Version in: header required: false schema: type: string enum: - '2026-09-09' description: >- Optional contract-version assertion. Omit it to use the app environment's pinned version. A different supported version is accepted only after that environment is explicitly migrated. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SetSettlementProfileRequest' examples: example: summary: Set account settlement preference request value: settlementDestinationId: destination_123 assetSymbol: USDC responses: '200': description: Settlement profile headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/SettlementProfile' examples: example: summary: Set account settlement preference 200 response value: id: settle_123 accountId: acct_123 version: 2 connectedWalletId: wallet_123 settlementDestinationId: destination_123 status: draft destinationType: smart_wallet chainId: 42161 destinationAddress: '11111111111111111111111111111111' assetSymbol: USDC tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' snapshot: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '424': $ref: '#/components/responses/FailedDependency' '429': $ref: '#/components/responses/TooManyRequests' security: - partnerBasicAuth: [] components: schemas: SetSettlementProfileRequest: type: object additionalProperties: false description: >- Select an active typed settlement destination returned by the settlement-destinations endpoint. Native assets cannot be selected for token settlement. THBT is Movement-only. JPYC is Polygon-only. USDG is Robinhood Chain-only (4663). required: - settlementDestinationId properties: settlementDestinationId: type: string example: destination_123 description: >- Use the ID returned by `GET /v2/accounts/{accountId}/settlement-destinations`. assetSymbol: type: string enum: - USDC - USDT - THBT - JPYC - USDG example: USDC SettlementProfile: type: object additionalProperties: false required: - id - accountId - version - connectedWalletId - settlementDestinationId - status - destinationType - chainId - destinationAddress - assetSymbol - tokenAddress - snapshot properties: id: type: string example: settle_123 accountId: type: string example: acct_123 version: type: integer minimum: 1 example: 2 connectedWalletId: type: - string - 'null' example: wallet_123 settlementDestinationId: type: - string - 'null' example: destination_123 status: type: string enum: - draft - active - inactive - failed destinationType: type: string enum: - smart_wallet - connected_wallet - external_wallet chainId: type: integer enum: - 42161 - 1 - 8453 - 137 - 56 - 43114 - 4663 - 4217 - 10103 - 10002 description: >- Supported settlement chain IDs: Arbitrum=42161, Ethereum=1, Base=8453, Polygon=137, BNB Smart Chain=56, Avalanche=43114, Robinhood Chain=4663, Tempo=4217, Solana=10103, Movement=10002. Settlement currently supports EVM, Solana, and Movement token destinations. Movement also supports THBT, while Polygon supports direct same-chain JPYC settlement. Tron is deposit-only for settlement-fee escrow. destinationAddress: type: string example: '11111111111111111111111111111111' assetSymbol: type: string enum: - USDC - USDT - THBT - JPYC - USDG tokenAddress: type: string example: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' snapshot: type: object additionalProperties: true createdAt: type: string format: date-time updatedAt: type: string format: date-time ErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - code - message properties: code: type: string minLength: 1 maxLength: 128 example: bad_request message: type: string minLength: 1 maxLength: 1000 example: The request is invalid details: {} responses: BadRequest: description: Bad request headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: BadRequest response value: error: code: bad_request message: The request is invalid details: example Unauthorized: description: Unauthorized headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: Unauthorized response value: error: code: bad_request message: The request is invalid details: example Forbidden: description: The app secret does not include the required scope headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: Forbidden response value: error: code: bad_request message: The request is invalid details: example NotFound: description: Not found headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: NotFound response value: error: code: bad_request message: The request is invalid details: example Conflict: description: Conflict headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: Conflict response value: error: code: bad_request message: The request is invalid details: example FailedDependency: description: Required chain, network, or provider configuration is missing headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: FailedDependency response value: error: code: bad_request message: The request is invalid details: example TooManyRequests: description: >- Rate limit, payment-option limit, selection cooldown, or temporary abuse block headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' Retry-After: description: Seconds until the caller should retry. schema: type: integer minimum: 1 RateLimit-Limit: description: Quota for the most constrained policy. schema: type: integer minimum: 1 RateLimit-Remaining: description: Requests remaining in that policy window. schema: type: integer minimum: 0 RateLimit-Reset: description: Seconds until that policy window resets. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: TooManyRequests response value: error: code: bad_request message: The request is invalid details: example securitySchemes: partnerBasicAuth: type: http scheme: basic description: >- HTTP Basic auth. Username is the Stableyard app ID. Password is the app secret. The optional Stableyard-Version request header must match the environment pin. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.