> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulate a collection (sandbox only)

> Sandbox only: lands `amount` of `asset` on your balance as test money. Answers `202` at once; the money credits within a few minutes through the ordinary collection path, so poll `GET /v2/collections` for it. A stablecoin deposit to your deposit address goes on `network`. If your organization has USD bank details, `USD` is a bank transfer to them: it credits as USDC with a `bank` source, less the deposit fees. No `Idempotency-Key`: a duplicate is just more test money. In every other environment this route answers `403 sandbox_only`.



## OpenAPI

````yaml /v2/openapi.json post /collections/simulate
openapi: 3.1.0
info:
  title: Jenzy Hermes Multi-asset API
  version: 2.0.0
  description: >-
    Hold and pay out across the assets enabled for your organization. Every
    amount is an exact decimal string beside an `asset` field. Authenticate with
    the same `jz_live_…` API key as `/v1`.
servers:
  - url: https://api.jenzy.com/v2
    description: Production
security: []
paths:
  /collections/simulate:
    post:
      summary: Simulate a collection (sandbox only)
      description: >-
        Sandbox only: lands `amount` of `asset` on your balance as test money.
        Answers `202` at once; the money credits within a few minutes through
        the ordinary collection path, so poll `GET /v2/collections` for it. A
        stablecoin deposit to your deposit address goes on `network`. If your
        organization has USD bank details, `USD` is a bank transfer to them: it
        credits as USDC with a `bank` source, less the deposit fees. No
        `Idempotency-Key`: a duplicate is just more test money. In every other
        environment this route answers `403 sandbox_only`.
      parameters:
        - $ref: '#/components/parameters/HermesOrg'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateCollectionCreate'
      responses:
        '202':
          description: >-
            Accepted, not yet credited. `id` is null (and `status` is `pending`)
            for a stablecoin deposit to your deposit address or a USD deposit,
            or when the sandbox’s answer was lost — the deposit may still land,
            so poll rather than retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulateCollection'
        '400':
          description: >-
            Malformed body or `amount` (see `GET /v2/assets` for the asset’s
            decimals), or a `USD` amount that does not cover the deposit fees.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing, malformed, or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: >-
            `sandbox_only` outside the sandbox; `corridor_not_enabled` for an
            asset not enabled for your organization; or the shell’s auth codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: >-
            `unsupported_asset` for an asset that cannot be simulated for your
            organization; `unsupported_network` for a `network` the asset does
            not run on (`USD` runs on `ethereum` only).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: The `/v2` shutter is closed — check `GET /v2/ping`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - ApiKeyAuth: []
components:
  parameters:
    HermesOrg:
      name: HERMES-ORG
      in: header
      required: false
      description: >-
        The id of one of your Child orgs. The call then acts on that Child org,
        not on your organization. If you do not send it, the call acts on your
        organization. An id that is not one of your Child orgs gives `404`.
      schema:
        type: string
        format: uuid
        example: 3f1c2a9e-8b7d-4e21-9a6f-0c5d4b3e2a10
  schemas:
    SimulateCollectionCreate:
      type: object
      properties:
        amount:
          anyOf:
            - type: integer
            - type: string
              pattern: ^\d+(\.\d+)?$
          description: >-
            An exact decimal string in the asset’s major unit, with at most the
            asset’s `decimals` (`"250000.00"`, `"12.5"`), or a JSON integer of
            whole units. Fractional JSON numbers are rejected — send a string.
            Parse with a decimal library, never a float.
          example: '250000.00'
        asset:
          type: string
          minLength: 1
          description: >-
            An asset code as `GET /v2/assets` lists it — uppercase, never
            compound (`USDC`, `USD`; never `USDC-ETHEREUM`). Network and rail
            live on the payment object.
          example: USDC
        network:
          type: string
          description: >-
            For a stablecoin deposit to your deposit address: the network by
            name (`ethereum`, `solana`). The asset must run on it, else
            `unsupported_network` (422). If you omit it, your default network is
            used. A `USD` deposit always lands on `ethereum`, whatever your
            default; any other `network` is `unsupported_network` (422).
          example: ethereum
      required:
        - amount
        - asset
    SimulateCollection:
      type: object
      properties:
        id:
          type:
            - string
            - 'null'
          description: >-
            The sandbox deposit id, or null for a stablecoin deposit to your
            deposit address or a USD deposit, or when the request reached the
            sandbox but its answer was lost — the deposit may still land. Do NOT
            retry on null; poll `GET /v2/collections`.
        asset:
          type: string
          minLength: 1
          description: >-
            An asset code as `GET /v2/assets` lists it — uppercase, never
            compound (`USDC`, `USD`; never `USDC-ETHEREUM`). Network and rail
            live on the payment object.
          example: USDC
        amount:
          type: string
          example: '1000.00'
        status:
          type: string
          description: >-
            `processing` at accept, or `pending` for a stablecoin or USD deposit
            or when the answer was lost; either way the credit appears in `GET
            /v2/collections` within a few minutes.
          example: processing
      required:
        - id
        - asset
        - amount
        - status
    ErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - validation_error
                - unauthorized
                - forbidden
                - not_found
                - conflict
                - rate_limited
                - internal_error
                - unknown_institution
                - invalid_mobile_number
                - invalid_account_number
                - mobile_number_institution_mismatch
                - service_unavailable
                - sandbox_only
                - insufficient_funds
                - rail_disabled
                - amount_limit_exceeded
                - org_limit_exceeded
                - service_incident
                - service_maintenance
                - onboarding_incomplete
                - access_suspended
                - corridor_not_enabled
                - unsupported_pair
                - invalid_wallet_address
                - rate_unavailable
                - quote_expired
                - quote_used
                - limit_exceeded
                - amount_below_minimum
                - unsupported_asset
                - unsupported_network
                - unsupported_media_type
                - payload_too_large
                - client_ref_used
                - beneficiary_required
                - beneficiary_not_allowed
                - proof_not_expected
                - invalid_beneficiary
                - beneficiary_exists
                - beneficiary_not_active
                - invoice_required
                - prohibited_industry
              description: >-
                Stable identifier a client may branch on — never renamed or
                removed.
            message:
              type: string
          required:
            - code
            - message
      required:
        - error
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: 'Your Jenzy API key: `Authorization: Bearer jz_live_…`'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.