> ## 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.

# Create an account Vault

> Create the single Arbitrum Safe/Zodiac stablecoin Vault for a UPA.

Each account has one Vault, on a chain Stableyard configures; you cannot select it. Choose an `ownershipMode`:

* `stableyard` returns a persisted `predictedSafeAddress` with status `provisioning` while deployment and policy installation continue in the background. That confirms the address is allocated, not deployed: wait for status `active` or the `vault.policy_active` webhook before funding or using the Vault. An already verified account email authorizes the initial managed policy automatically; otherwise complete the returned contact-verification action. `managedContact` must match the UPA's verified email if it has one. The configured platform multisig is the final owner.
* `external` is for account owners who sign policy changes themselves.

`Idempotency-Key` is required; reuse it only with the identical request. See [Treasury settlement](/settlement/treasury-settlement).


## OpenAPI

````yaml openapi.json POST /v2/accounts/{accountId}/vault
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}/vault:
    post:
      tags:
        - Vaults
      summary: Create account vault
      description: >-
        Creates the account's single Arbitrum Safe/Zodiac stablecoin Vault.
        `stableyard` creation returns a persisted predictedSafeAddress with
        status provisioning while deployment and policy installation continue in
        the background. This confirms address allocation; wait for status active
        or vault.policy_active before funding or using the Vault. An already
        verified account email automatically authorizes the initial managed
        policy. Otherwise complete the returned contact-verification action. Use
        `external` when the account owner signs policy changes. The configured
        platform multisig is the final owner of a Stableyard-controlled Vault.
        The chain is configured by Stableyard and is not caller-selectable.
      operationId: createVault
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            example: acct_123
          description: Canonical account id returned by the Accounts API.
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            example: payment-request-001
          description: Required retry key. Reuse only with the identical vault request.
        - 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:
              type: object
              additionalProperties: false
              required:
                - ownershipMode
              properties:
                ownershipMode:
                  type: string
                  enum:
                    - external
                    - stableyard
                owner:
                  type: object
                  additionalProperties: false
                  required:
                    - type
                    - addressType
                    - address
                  properties:
                    type:
                      type: string
                      enum:
                        - external_owner
                        - partner_multisig
                    addressType:
                      type: string
                      enum:
                        - evm
                    address:
                      type: string
                      example: '0xdFD4ab80E163D6864E26F37540563cBf2E52A582'
                managedContact:
                  type: object
                  additionalProperties: false
                  required:
                    - email
                  description: >-
                    Canonical UPA email used for managed policy authorization.
                    The initial policy OTP also verifies this email for KYC and
                    fiat services. If the UPA already has a verified email, this
                    value must match it.
                  properties:
                    email:
                      type: string
                      format: email
                      example: alice@example.com
                initialPolicy:
                  $ref: '#/components/schemas/VaultPolicyInput'
            examples:
              example:
                summary: Create account vault request
                value:
                  ownershipMode: external
                  owner:
                    type: external_owner
                    addressType: evm
                    address: '0xdFD4ab80E163D6864E26F37540563cBf2E52A582'
                  managedContact:
                    email: alice@example.com
                  initialPolicy:
                    spendLimit:
                      amountAtomic: '500000000'
                    allowedTokens:
                      - USDC
                    yield:
                      provider: none
      responses:
        '200':
          description: Vault
          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/VaultResource'
              examples:
                example:
                  summary: Create account vault 200 response
                  value:
                    id: vault_123
                    accountId: acct_123
                    chainId: 42161
                    ownershipMode: external
                    status: pending_authorization
                    predictedSafeAddress: null
                    monitoring:
                      provider: alchemy
                      status: registered
                      registeredAt: null
                    earning:
                      enabled: true
                      provider: none
                      currentApyBps: null
                      earnedAmountRaw: null
                    resourceVersion: 1
                    createdAt: '2026-08-28T10:00:00.000Z'
                    updatedAt: '2026-08-28T10:00:00.000Z'
        '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:
    VaultPolicyInput:
      type: object
      additionalProperties: false
      properties:
        spendLimit:
          type: object
          additionalProperties: false
          properties:
            amountAtomic:
              type: string
              pattern: ^[0-9]+$
              example: '500000000'
              description: >-
                Delegated Vault payment cap for each fixed 30-day cycle, using
                six-decimal USD atomic units. 500000000 means 500 USD. A signed
                policy update preserves usage and the existing reset time
                instead of refilling the allowance.
        allowedTokens:
          type: array
          minItems: 1
          maxItems: 2
          items:
            type: string
            enum:
              - USDC
              - USDT
          example:
            - USDC
        yield:
          type: object
          additionalProperties: false
          properties:
            provider:
              type: string
              enum:
                - none
                - aave
                - morpho
              default: none
              description: >-
                Select one yield provider. Changing providers requires a signed
                policy update and an empty Vault/yield position.
    VaultResource:
      type: object
      additionalProperties: false
      required:
        - id
        - accountId
        - chainId
        - ownershipMode
        - status
        - resourceVersion
        - monitoring
        - earning
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: vault_123
        accountId:
          type: string
          example: acct_123
        chainId:
          type: integer
          example: 42161
        ownershipMode:
          type: string
          enum:
            - external
            - stableyard
        status:
          type: string
          enum:
            - pending_authorization
            - provisioning
            - awaiting_policy
            - active
            - suspended
            - failed
            - requires_intervention
        safeAddress:
          type:
            - string
            - 'null'
        predictedSafeAddress:
          type:
            - string
            - 'null'
          description: >-
            Allocated Safe address, persisted before managed creation returns.
            The address is not evidence of deployment or readiness to receive
            funds. Wait for status active before funding or using the Vault.
        rolesModuleAddress:
          type:
            - string
            - 'null'
        activePolicyId:
          type:
            - string
            - 'null'
        activePolicy:
          oneOf:
            - $ref: '#/components/schemas/VaultPolicyResource'
              title: Active Vault policy
            - title: No active Vault policy
              type: 'null'
        latestPolicy:
          oneOf:
            - $ref: '#/components/schemas/VaultPolicyResource'
              title: Latest Vault policy
            - title: No Vault policy
              type: 'null'
        nextAction:
          oneOf:
            - $ref: '#/components/schemas/VaultAction'
              title: Vault action required
            - title: No Vault action required
              type: 'null'
        pendingActions:
          type: array
          items:
            $ref: '#/components/schemas/VaultAction'
        spendUsage:
          $ref: '#/components/schemas/VaultSpendUsage'
        mandates:
          type: array
          items:
            type: object
            additionalProperties: true
        monitoring:
          type: object
          additionalProperties: false
          required:
            - provider
            - status
            - registeredAt
          properties:
            provider:
              type: string
              example: alchemy
            status:
              type: string
              example: registered
            registeredAt:
              type:
                - string
                - 'null'
              format: date-time
        earning:
          type: object
          additionalProperties: false
          required:
            - enabled
            - provider
            - currentApyBps
            - earnedAmountRaw
          properties:
            enabled:
              type: boolean
            provider:
              type: string
              enum:
                - none
                - aave
                - morpho
            currentApyBps:
              type:
                - integer
                - 'null'
            earnedAmountRaw:
              type:
                - string
                - 'null'
        resourceVersion:
          type: integer
          minimum: 1
        failureCode:
          type:
            - string
            - 'null'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    VaultPolicyResource:
      type: object
      additionalProperties: false
      required:
        - id
        - vaultId
        - version
        - policySchemaVersion
        - status
        - ownershipMode
        - allowedTokens
        - spendLimits
        - yieldRules
        - resourceVersion
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: vault_policy_123
        vaultId:
          type: string
          example: vault_123
        version:
          type: integer
          minimum: 1
        policySchemaVersion:
          type: integer
          minimum: 1
        status:
          type: string
          enum:
            - draft
            - pending_authorization
            - authorized
            - installing
            - active
            - superseded
            - revoked
            - failed
        ownershipMode:
          type: string
          enum:
            - external
            - stableyard
        allowedTokens:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - symbol
              - chainId
              - tokenAddress
              - decimals
            properties:
              symbol:
                type: string
                enum:
                  - USDC
                  - USDT
              chainId:
                type: integer
                example: 42161
              tokenAddress:
                type: string
                example: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
              decimals:
                type: integer
                const: 6
        spendLimits:
          type: object
          additionalProperties: false
          required:
            - spendLimitAtomic
            - currency
            - decimals
            - period
            - periodSeconds
            - enforcement
          properties:
            spendLimitAtomic:
              type: string
              pattern: ^[1-9][0-9]*$
              example: '500000000'
            currency:
              type: string
              const: USD
            decimals:
              type: integer
              const: 6
            period:
              type: string
              const: fixed_30_day
            periodSeconds:
              type: integer
              const: 2592000
            enforcement:
              type: string
              const: zodiac_allowance_plus_inflight_database_reservations
        yieldRules:
          type: object
          additionalProperties: false
          required:
            - provider
            - mode
          properties:
            provider:
              type: string
              enum:
                - none
                - aave
                - morpho
            mode:
              type: string
              enum:
                - disabled
                - auto_supply_and_redeem_before_payment
        authorization:
          type: object
          additionalProperties: true
          description: Present on single-policy responses while authorization is pending.
        nextAction:
          oneOf:
            - $ref: '#/components/schemas/VaultAction'
              title: Vault action required
            - title: No Vault action required
              type: 'null'
        reason:
          type:
            - string
            - 'null'
        resourceVersion:
          type: integer
          minimum: 1
        failureCode:
          type:
            - string
            - 'null'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    VaultAction:
      type: object
      additionalProperties: false
      required:
        - id
        - vaultId
        - type
        - status
        - resourceVersion
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: vault_action_123
        vaultId:
          type: string
          example: vault_123
        policyId:
          type:
            - string
            - 'null'
          example: vault_policy_123
        type:
          type: string
          enum:
            - sign_policy
            - approve_managed_policy
            - install_policy
            - auto_supply_yield
            - redeem_yield
            - execute_payment
        status:
          type: string
          enum:
            - pending
            - queued
            - processing
            - completed
            - failed
            - cancelled
        nextAction:
          type:
            - object
            - 'null'
          additionalProperties: true
          description: >-
            Public wallet, signature, email approval, or wait instruction. Treat
            the action type as the discriminator and never modify transaction
            calldata. `execute_safe_transaction` includes a `completion` request
            descriptor for submitting the mined transaction hash.
        resourceVersion:
          type: integer
          minimum: 1
        failureCode:
          type:
            - string
            - 'null'
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    VaultSpendUsage:
      type: object
      additionalProperties: false
      required:
        - vaultId
        - status
        - period
        - periodSeconds
        - supportedAssets
      properties:
        vaultId:
          type: string
          example: vault_123
        status:
          type: string
          enum:
            - active
            - not_active
        reason:
          type: string
          description: Present when status is not_active.
        period:
          type: string
          const: fixed_30_day
        periodSeconds:
          type: integer
          const: 2592000
        limitUsdAtomic:
          type: string
          pattern: ^[0-9]+$
        limitAtomic:
          type: string
          pattern: ^[0-9]+$
        consumedAtomic:
          type: string
          pattern: ^[0-9]+$
        onchainConsumedAtomic:
          type: string
          pattern: ^[0-9]+$
        settledRecordedAtomic:
          type: string
          pattern: ^[0-9]+$
        pendingAtomic:
          type: string
          pattern: ^[0-9]+$
        availableAtomic:
          type: string
          pattern: ^[0-9]+$
        windowStartedAt:
          type: string
          format: date-time
        resetsAt:
          type: string
          format: date-time
        observedAt:
          type: string
          format: date-time
        supportedAssets:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - symbol
              - chainId
              - tokenAddress
              - decimals
            properties:
              symbol:
                type: string
                enum:
                  - USDC
                  - USDT
              chainId:
                type: integer
              tokenAddress:
                type: string
              decimals:
                type: integer
                const: 6
    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.