> ## 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 stablecoin Vault for a UPA.

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

* `stableyard` returns the allocated Vault address in `predictedSafeAddress`, with status `provisioning`, while deployment and policy installation continue in the background. 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. Stableyard's platform multisig is the final owner.
* `external` is for account owners who sign policy changes themselves. After each authorization, the owner executes the returned transaction; see [Authorize a Vault policy](/api-reference/vault-policies/authorize-policy).

`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
  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 documented in the
    separate Interfaces & SDKs reference.
  x-stableyard-documentation-surface: partner
servers:
  - url: https://prod-api.stableyard.fi
    description: Production
  - url: https://staging-api-v2.stableyard.fi
    description: Sandbox
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 identity verification. Managed vaults and
      fiat payment rails use this same verified UPA identity.
  - name: Vaults
    description: >-
      Create policy-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 stablecoin Vault. `stableyard`
        creation returns the allocated Vault address in `predictedSafeAddress`
        with status provisioning until the Vault is ready. The address confirms
        allocation only; 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 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: request-key-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: '0x3333333333333333333333333333333333333333'
                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: '0x3333333333333333333333333333333333333333'
                  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
                    safeAddress: null
                    predictedSafeAddress: null
                    rolesModuleAddress: null
                    monitoring:
                      provider: example
                      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'
          description: The Vault's smart-account address once it is deployed.
        predictedSafeAddress:
          type:
            - string
            - 'null'
          description: >-
            Allocated Vault address. It is not evidence of deployment or
            readiness to receive funds. Wait for status active before funding or
            using the Vault.
        rolesModuleAddress:
          type:
            - string
            - 'null'
          description: Address of the Vault's on-chain policy module.
        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
              description: Opaque reference. Do not depend on its value.
            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
              description: >-
                Informational enforcement identifier. Do not depend on its
                value.
        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` is an on-chain transaction the
            Vault owner must execute; it 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
                example: 42161
              tokenAddress:
                type: string
                example: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
              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: bad_request
              value:
                error:
                  code: bad_request
                  message: The request is invalid
    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
              value:
                error:
                  code: unauthorized
                  message: Authentication is required
    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
              value:
                error:
                  code: forbidden
                  message: The credential does not allow this operation
    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: not_found
              value:
                error:
                  code: not_found
                  message: The resource was not found
    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: idempotency_conflict
              value:
                error:
                  code: idempotency_conflict
                  message: >-
                    The Idempotency-Key was already used with a different
                    request
    FailedDependency:
      description: This feature is not configured for your app or environment
      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: chain_config_missing
              value:
                error:
                  code: chain_config_missing
                  message: The requested network is not configured for this environment
    TooManyRequests:
      description: Too many requests. Retry after the `Retry-After` interval.
      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: rate_limited
              value:
                error:
                  code: rate_limited
                  message: Too many requests
  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.