Sign in

v1

latestOpenAPI 3.1.0Proprietary2026-07-2464170247.4 KB
Auto-Conversion Rules

Create Auto-Conversion Rule

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.
post/v1/customers/{customer_id}/auto-conversion-rules

Path parameters

customer_idstring required

Customer ID (UUID format)

Headers

Idempotency-Keystring required

Required. UUID v4 for idempotent request. Same key returns existing Auto-Conversion Rule if already created.

Request body

Example request

{
  "source": {
    "asset": "USDC",
    "network": "ETHEREUM"
  },
  "destination": {
    "asset": "USDC",
    "network": "ETHEREUM",
    "wallet_address": "0x71a6c6be0be5f28ef4ea7541749d90d9c66fec7d",
    "external_account_id": "381b013e-8893-11f0-b308-2eaa4f6974f2"
  }
}

Response

Auto-Conversion Rule created successfully with deposit info

customer_idstring required

Portfolio ID — also exposed as customer_id in OpenAPI. Identifies one individual application / portfolio row within an entity.

account_idstring nullable

External account identifier of the owning customer

auto_conversion_rule_idstring required

Unique Auto-Conversion Rule identifier (UUID)

idempotency_keystring required

HTTP Idempotency-Key header value. Stricter than other IDs: ≤64 ASCII chars per the common REST API convention.

nicknamestring required

Auto-generated nickname based on source/destination

status'Pending' | 'Active' | 'Inactive' | 'Failed' required

Instruction Status - defines the lifecycle state of an instruction

deposit_info_statusstring

Status of source deposit info: PENDING (not yet active), ACTIVE (available), INACTIVE (temporarily unavailable)

created_atstring required

Auto-Conversion Rule creation timestamp (ISO 8601)

modified_atstring required

Last modification timestamp (ISO 8601)

Example response

{
  "customer_id": "14f20ebd-893b-11f0-b308-2eaa4f6974f2",
  "account_id": "BZ-A2C4-9XPN",
  "auto_conversion_rule_id": "e9ece207-8fd6-400e-872b-409701e57b74",
  "nickname": "My USD to USDC Rule",
  "source": {
    "asset": "USDC",
    "network": "ETHEREUM"
  },
  "destination": {
    "asset": "USDC",
    "network": "ETHEREUM",
    "wallet_address": "0x71a6c6be0be5f28ef4ea7541749d90d9c66fec7d",
    "external_account_id": "381b013e-8893-11f0-b308-2eaa4f6974f2"
  },
  "deposit_info_status": "ACTIVE",
  "source_deposit_info": {
    "network": "wire",
    "reference_code": "25BO475M7V",
    "recipient_name": "1Money Company, LLC",
    "bank_name": "Sample Bank Name",
    "routing_number": "121140399",
    "account_holder_name": "Atomic Brokerage LLC",
    "account_number": "123-456789-0",
    "country_code": "USA",
    "street": "1234 5th Avenue, New York, NY 10011",
    "city": "New York",
    "region": "NY",
    "postal_code": "10011",
    "bic_code": "ABCDEF00",
    "minimum_deposit_amount": "1"
  },
  "created_at": "2025-01-12T10:00:00Z",
  "modified_at": "2025-01-12T14:30:00Z"
}