---
title: "Create Auto-Conversion Rule"
method: POST
path: "/v1/customers/{customer_id}/auto-conversion-rules"
tags: ["Auto-Conversion Rules"]
---

# Create Auto-Conversion Rule

`POST /v1/customers/{customer_id}/auto-conversion-rules`

Create an Auto-Conversion Rule for fiat->crypto, crypto->fiat, or crypto->crypto conversions.

**Supported Assets:**
- `USD`, `USDC`, `USDT`, `PYUSD`, `RLUSD`, `USDG`, `USDP`, `EURC`, `MXNB`
**Supported Networks:**
- Fiat deposit networks: `US_FEDWIRE`, `SWIFT`
- Crypto networks: `ETHEREUM`, `POLYGON`, `BASE`, `ARBITRUM`, `AVALANCHE`, `BNBCHAIN`, `SOLANA`, `TRON`

**Validation Rules:**
- Supported pairs: fiat->crypto, crypto->fiat, and crypto->crypto; fiat->fiat is NOT supported
- `Idempotency-Key` header is required and must be a valid UUID v4
- Source network must match asset type (fiat asset requires fiat network, crypto asset requires crypto network)
- For crypto withdrawal destination: `network` is required when `wallet_address` is provided
- For fiat destination: `network` will be omitted

**Withdrawal Configuration:**
- Fiat-to-Crypto or Crypto->Crypto with withdrawal: provide `wallet_address` (external crypto wallet address)
- Crypto-to-Fiat with withdrawal: provide `external_account_id` (bank account ID from external-accounts API)
- Conversion-only (no withdrawal): omit both fields, converted funds remain in customer's account

**Idempotency & Webhook Behavior:**
- This endpoint creates resources asynchronously. The webhook notification may arrive **before** the HTTP response returns.
- Use the `Idempotency-Key` to query the resource status via webhook response, enabling proper idempotency control.
- **Recommended flow:** Instead of waiting for the HTTP response and then the webhook, clients can use the webhook arrival as the completion signal and query by `Idempotency-Key` to verify the result.
- This approach prevents "dangling wait" scenarios where clients unnecessarily wait for the HTTP response when the webhook has already confirmed the outcome.

**Response & Status:**
- The response will have `status=PENDING` and `source_deposit_info=null` because deposit info is being prepared asynchronously.
- Once deposit info is ready, the status will transition to `ACTIVE` and `source_deposit_info` will contain bank deposit details or crypto wallet address.
- Use the retrieve endpoint or webhook to get the full details when the rule becomes `ACTIVE`.

## Path parameters

- `customer_id` string, required

## Headers

- `Idempotency-Key` string, required

## Request body

- OpenApiAutoConversionRuleCreationRequest — Request body for creating a new Auto-Conversion Rule.
  - `source` OpenApiSourceAssetInfo, required — Source asset information for Auto-Conversion Rule
    - `asset` string, required — - Stablecoin assets: USDC, USDT, PYUSD, RLUSD, USDG, USDP, EURC, MXNB, 1USD(1USD/USDC conversion only, deposit/withdrawal not supported) - Digital assets: BTC - Fiat currencies: USD
    - `network` string, required
  - `destination` OpenApiDestinationAssetInfo, required — Destination asset information for Auto-Conversion Rule
    - `asset` string, required — - Stablecoin assets: USDC, USDT, PYUSD, RLUSD, USDG, USDP, EURC, MXNB, 1USD(1USD/USDC conversion only, deposit/withdrawal not supported) - Digital assets: BTC - Fiat currencies: USD
    - `network` string
    - `wallet_address` string, nullable — Wallet address for automatic crypto withdrawal (fiat->crypto or crypto->crypto). Omit for conversion-only.
    - `external_account_id` string, nullable — External account ID for automatic fiat withdrawal (crypto->fiat only). Omit for conversion-only.

## Response `201`

Auto-Conversion Rule created successfully with deposit info

- OpenApiAutoConversionRuleResponse — Auto-Conversion Rule response object
  - `customer_id` string, required — Portfolio ID — also exposed as `customer_id` in OpenAPI. Identifies one individual application / portfolio row within an entity.
  - `account_id` string, nullable — External account identifier of the owning customer
  - `auto_conversion_rule_id` string, required — Unique Auto-Conversion Rule identifier (UUID)
  - `idempotency_key` string, required — HTTP `Idempotency-Key` header value. Stricter than other IDs: ≤64 ASCII chars per the common REST API convention.
  - `nickname` string, required — Auto-generated nickname based on source/destination
  - `status` 'Pending' | 'Active' | 'Inactive' | 'Failed', required — Instruction Status - defines the lifecycle state of an instruction
  - `source` OpenApiSourceAssetInfo, required — Source asset information for Auto-Conversion Rule
    - `asset` string, required — - Stablecoin assets: USDC, USDT, PYUSD, RLUSD, USDG, USDP, EURC, MXNB, 1USD(1USD/USDC conversion only, deposit/withdrawal not supported) - Digital assets: BTC - Fiat currencies: USD
    - `network` string, required
  - `destination` OpenApiDestinationAssetInfo, required — Destination asset information for Auto-Conversion Rule
    - `asset` string, required — - Stablecoin assets: USDC, USDT, PYUSD, RLUSD, USDG, USDP, EURC, MXNB, 1USD(1USD/USDC conversion only, deposit/withdrawal not supported) - Digital assets: BTC - Fiat currencies: USD
    - `network` string
    - `wallet_address` string, nullable — Wallet address for automatic crypto withdrawal (fiat->crypto or crypto->crypto). Omit for conversion-only.
    - `external_account_id` string, nullable — External account ID for automatic fiat withdrawal (crypto->fiat only). Omit for conversion-only.
  - `deposit_info_status` string — Status of source deposit info: PENDING (not yet active), ACTIVE (available), INACTIVE (temporarily unavailable)
  - `source_deposit_info` union — Source deposit info (bank for fiat, wallet for crypto)
    - OpenApiBankDepositInfo — Bank deposit info for fiat source (USD via Wire/SWIFT)
      - `network` string, required — Network type: wire or swift
      - `reference_code` string, required — Reference code (memo) - IMPORTANT: Must include this in your wire transfer for proper routing
      - `recipient_name` string — Optional recipient display name from the bank instruction provider. For fiat deposits, use `account_holder_name` as the beneficiary/account name when entering bank transfer details. This field is retained for backward compatibility and may be absent or duplicate `account_holder_name`.
      - `bank_name` string — Receiving bank name
      - `routing_number` string — Bank routing number (for US domestic transfers)
      - `account_holder_name` string — Beneficiary/account holder name to use when sending a fiat bank transfer. Prefer this field over `recipient_name` when both fields are present.
      - `account_number` string — Bank account number
      - `country_code` string — Country code (ISO 3166-1 alpha-3)
      - `street` string — Bank street address
      - `additional` string, nullable — Additional address information
      - `city` string — City
      - `region` string — State/Region
      - `postal_code` string — Postal/ZIP code
      - `bic_code` string — BIC/SWIFT code for international wire transfers
      - `minimum_deposit_amount` string, required — Minimum deposit amount required
    - OpenApiCryptoDepositInfo — Crypto wallet deposit info for crypto source (USDC/USDT)
      - `wallet_address` string, required — Wallet address for receiving crypto deposits. Send tokens to this address.
      - `minimum_deposit_amount` string, required — Minimum deposit amount required
      - `contract_address` string, required — Token contract address (ERC-20). Empty string for native tokens.
  - `created_at` string, required — Auto-Conversion Rule creation timestamp (ISO 8601)
  - `modified_at` string, required — Last modification timestamp (ISO 8601)

## Other responses

- `400` — Validation failed: invalid currency pair, missing network, invalid Idempotency-Key format, or asset/network mismatch
- `401` — Authentication failed - invalid or missing API key
- `405` — Method not allowed
- `409` — Conflict - Auto-Conversion Rule with this Idempotency-Key already exists for this customer
- `422` — Unprocessable Entity - Invalid enum value (e.g., unsupported network or asset name)
- `500` — Internal server error

---

[API](https://skmtc.net/1money/apis/1money-openapi.md) · [All operations](https://skmtc.net/1money/apis/1money-openapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/1money/1money-openapi/revisions/aa2718d28cb5/schema)