> ## Documentation Index > Fetch the complete documentation index at: https://docs.bastion.com/llms.txt > Use this file to discover all available pages before exploring further. # Submit Conversion > Submit a conversion on behalf of an account ## OpenAPI ````yaml /v2/openapi.yaml post /v2/conversions openapi: 3.1.0 info: title: Bastion APIs version: '2.0' servers: - url: https://api.prod.bastion.com description: Production environment - url: https://api.sandbox.bastion.io description: Sandbox environment security: - auth: [] tags: - name: Bastion APIs paths: /v2/conversions: post: tags: - Conversions summary: Submit Conversion description: Submit a conversion on behalf of an account operationId: bastion.api.v2.API.SubmitConversion requestBody: content: application/json: schema: $ref: >- #/components/schemas/bastion.api.v2.conversions.ConversionRequest required: true responses: '201': description: Success content: application/json: schema: $ref: '#/components/schemas/bastion.api.v2.conversions.Conversion' '400': description: Bad request '401': description: Unauthorized Request '403': description: Request Forbidden '404': description: Resource not found '500': description: Internal Server Error components: schemas: bastion.api.v2.conversions.ConversionRequest: type: object properties: request_id: type: string title: request_id pattern: >- [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12} format: uuid description: Request identifier in UUID format. Serves as an idempotency key. amount: type: string title: amount description: Amount to be converted in source currency. Maximum 2 decimal places. account_id: type: string title: account_id description: Account ID to debit for the conversion. payment_purpose: $ref: '#/components/schemas/bastion.api.v2.conversions.PaymentPurpose' title: payment_purpose description: Purpose of the payment source: $ref: '#/components/schemas/bastion.api.v2.conversions.ConversionSource' title: source description: Source of the conversion destination: $ref: >- #/components/schemas/bastion.api.v2.conversions.ConversionDestination title: destination description: Destination of the conversion quote_id: type: string title: quote_id description: >- (OPTIONAL) Quote ID from a prior GET /v2/conversions/quotes response. Required for off-ramp conversions. device_signals: oneOf: - $ref: '#/components/schemas/bastion.common.DeviceSignals' - type: 'null' title: device_signals description: (OPTIONAL) Signals about the device initiating the conversion title: ConversionRequest required: - request_id - amount - account_id - payment_purpose - source - destination additionalProperties: false bastion.api.v2.conversions.Conversion: type: object properties: id: type: string title: id description: |- Server-generated unique conversion ID (KSUID). This is the canonical transaction identifier; use it on end-user receipts and references. readOnly: true request_id: type: string title: request_id pattern: >- [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12} format: uuid description: |- Client-provided request_id (UUID). Idempotency key for internal reconciliation only; do not surface on end-user receipts — use `id`. amount: type: string title: amount description: Amount in source currency. account_id: type: string title: account_id description: Account ID debited for the conversion payment_purpose: $ref: '#/components/schemas/bastion.api.v2.conversions.PaymentPurpose' title: payment_purpose description: Purpose of the payment source: $ref: '#/components/schemas/bastion.api.v2.conversions.ConversionSource' title: source description: Source configuration destination: $ref: >- #/components/schemas/bastion.api.v2.conversions.ConversionDestination title: destination description: Destination configuration type: $ref: '#/components/schemas/bastion.api.v2.conversions.ConversionType' title: type description: Inferred conversion type readOnly: true status: $ref: '#/components/schemas/bastion.api.v2.conversions.ConversionStatus' title: status description: Current external status of the conversion readOnly: true source_deposit_instructions: $ref: '#/components/schemas/bastion.api.v2.conversions.DepositInstructions' title: source_deposit_instructions description: (OPTIONAL) Deposit instructions for MemoID On-Ramp. created_at: type: string title: created_at description: Timestamps readOnly: true updated_at: type: string title: updated_at readOnly: true completed_at: type: string title: completed_at description: Timestamp for when conversion reached terminal COMPLETED status. readOnly: true exchange_rate: type: string title: exchange_rate description: The exchange rate applied to the conversion. readOnly: true fees_total: type: string title: fees_total description: Rolled-up total of all fees visible to the end user. readOnly: true destination_currency: type: string title: destination_currency description: Destination currency symbol (e.g., "USD", "MXN", "KRW"). readOnly: true fees: type: array items: $ref: '#/components/schemas/bastion.api.v2.conversions.Fee' title: fees description: Itemized fee breakdown. readOnly: true fee_model: $ref: '#/components/schemas/bastion.common.FeeModel' title: fee_model description: >- Fee model applied to this conversion. INCLUSIVE means fees are deducted from the source amount so the user sends exactly the quoted amount. readOnly: true fees_total_currency: $ref: '#/components/schemas/bastion.api.v2.conversions.ConversionCurrency' title: fees_total_currency description: Currency that fees_total is expressed in. readOnly: true quote_id: type: string title: quote_id description: Quote referenced on submit. readOnly: true failure_reason: type: - string - 'null' title: failure_reason description: >- Human-readable reason when the conversion failed, was canceled, or was returned. Omitted when unset. readOnly: true refund_details: oneOf: - $ref: '#/components/schemas/bastion.api.v2.conversions.RefundDetails' - type: 'null' title: refund_details description: Present only when status is RETURNED. readOnly: true title: Conversion required: - request_id - amount - account_id - payment_purpose - source - destination additionalProperties: false bastion.api.v2.conversions.PaymentPurpose: type: string title: PaymentPurpose enum: - PAYMENT_PURPOSE_UNSPECIFIED - SALARY_PAYMENT - PERSONAL_REMITTANCE - RENT_PAYMENT - PROPERTY_PURCHASE - OWNED_ACCOUNT_ABROAD - ADVERTISING_EXPENSES - ADVISORY_FEES - BUSINESS_INSURANCE - CONSTRUCTION - DELIVERY_FEES - EDUCATION - EXPORTS - DONATION - HOTEL - LOAN_PAYMENT - MAINTENANCE_EXPENSES - MEDICAL_EXPENSE - OFFICE_EXPENSES - ROYALTY_FEES - SERVICE_CHARGE - SHARES_INVESTMENT - TAX_PAYMENT - TRANSPORTATION_FEES - TRAVEL - UTILITY_BILLS - INTERNAL_BUSINESS_MOVEMENT description: Purpose of payment example: SALARY_PAYMENT bastion.api.v2.conversions.ConversionSource: type: object properties: currency: $ref: '#/components/schemas/bastion.api.v2.conversions.ConversionCurrency' title: currency description: >- Currency of the source (e.g., USDC or USDT for off-ramp, USD for on-ramp) payment_method: $ref: '#/components/schemas/bastion.api.v2.conversions.PaymentMethod' title: payment_method description: 'Transfer mechanism: BLOCKCHAIN, WIRE, ACH.' chain: oneOf: - $ref: '#/components/schemas/bastion.common.Chain' - type: 'null' title: chain description: >- (OPTIONAL) Blockchain network. Required when payment_method = BLOCKCHAIN. e.g., SOLANA_MAINNET, ETHEREUM_MAINNET, BASE_MAINNET. Omitted for fiat sources. amount: type: - string - 'null' title: amount description: Amount in source currency. readOnly: true total: type: - string - 'null' title: total description: >- All-in wallet debit in source currency (principal plus fees where applicable). readOnly: true title: ConversionSource required: - currency - payment_method additionalProperties: false description: Source of the conversion bastion.api.v2.conversions.ConversionDestination: type: object properties: currency: $ref: '#/components/schemas/bastion.api.v2.conversions.ConversionCurrency' title: currency description: >- Currency of the destination (e.g., USD for off-ramp, USDC or USDT for on-ramp) payment_method: $ref: '#/components/schemas/bastion.api.v2.conversions.PaymentMethod' title: payment_method description: 'Transfer mechanism: BLOCKCHAIN, WIRE, ACH.' chain: oneOf: - $ref: '#/components/schemas/bastion.common.Chain' - type: 'null' title: chain description: >- (OPTIONAL) Blockchain network. Required when payment_method = BLOCKCHAIN. e.g., SOLANA_MAINNET, ETHEREUM_MAINNET, BASE_MAINNET. Omitted for fiat destinations. payment_instructions_id: type: string title: payment_instructions_id description: >- (OPTIONAL) Required when destination is fiat: the ID of the pre-registered payment instructions for receiving fiat. amount: type: - string - 'null' title: amount description: Amount delivered in destination currency. readOnly: true country: oneOf: - $ref: '#/components/schemas/bastion.common.Country' - type: 'null' title: country description: >- Destination country (ISO 3166-1 alpha-2). Populated for fiat off-ramps. readOnly: true title: ConversionDestination required: - currency - payment_method additionalProperties: false description: Destination of the conversion bastion.common.DeviceSignals: type: object properties: ip_address: type: string title: ip_address description: Accepts either IPv4 or IPv6 addresses device_id: type: string title: device_id description: >- Opaque string; format varies by platform (Apple/Google/Samsung-Android). title: DeviceSignals additionalProperties: false description: |- DeviceSignals carries client device/network identifiers captured at request time for value-moving, user-initiated endpoints. bastion.api.v2.conversions.ConversionType: type: string title: ConversionType enum: - CONVERSION_TYPE_UNSPECIFIED - ON_RAMP - OFF_RAMP description: Inferred type of the conversion. example: ON_RAMP bastion.api.v2.conversions.ConversionStatus: type: string title: ConversionStatus enum: - CONVERSION_STATUS_UNSPECIFIED - INITIATED - PROCESSING - IN_REVIEW - PAYOUT_INITIATED - PAYOUT_COMPLETED - COMPLETED - FAILED - CANCELLED - RETURNED description: Current external status of the conversion. example: INITIATED bastion.api.v2.conversions.DepositInstructions: type: object properties: amount: type: string title: amount description: Amount to be deposited currency: $ref: '#/components/schemas/bastion.api.v2.conversions.ConversionCurrency' title: currency description: Currency of the fiat transaction bank_name: type: string title: bank_name description: Name of the bank bank_address: type: string title: bank_address description: Address of the bank payment_method: $ref: '#/components/schemas/bastion.api.v2.conversions.PaymentMethod' title: payment_method description: Payment method for the transaction deposit_message: type: string title: deposit_message description: Deposit message bank_account_number: type: string title: bank_account_number description: Bank account number bank_routing_number: type: string title: bank_routing_number description: Bank routing number bank_beneficiary_name: type: string title: bank_beneficiary_name description: Name of the bank beneficiary bank_beneficiary_address: type: string title: bank_beneficiary_address description: Address of the bank beneficiary title: DepositInstructions additionalProperties: false description: Deposit instructions for on-ramp conversions. bastion.api.v2.conversions.Fee: type: object properties: amount: type: string title: amount description: Fee amount as a decimal string (e.g. "2.50"). currency: $ref: '#/components/schemas/bastion.api.v2.conversions.ConversionCurrency' title: currency description: Currency the fee is denominated in. type: $ref: '#/components/schemas/bastion.common.FeeType' title: type description: Category of the fee (e.g. platform fee). fee_percent: type: string title: fee_percent description: >- Percentage rate on the DEVELOPER line (informational; omitted on PLATFORM). readOnly: true title: Fee additionalProperties: false description: Individual fee line item on a conversion. bastion.common.FeeModel: type: string title: FeeModel enum: - FEE_MODEL_UNSPECIFIED - INCLUSIVE - DEDUCTED - ON_TOP description: Fee model for a conversion. example: INCLUSIVE bastion.api.v2.conversions.ConversionCurrency: type: string title: ConversionCurrency enum: - CONVERSION_CURRENCY_UNSPECIFIED - USDC - USD - MXN - INR - KRW - USDT - GHS - EUR description: |- Currency of a conversion. The currency can be a stablecoin or a fiat currency. example: USDC bastion.api.v2.conversions.RefundDetails: type: object properties: refund_amount: type: - string - 'null' title: refund_amount readOnly: true tx_hash: type: - string - 'null' title: tx_hash description: >- Cross-app credit transfer (intermediary → customer). Not the inbound Borderless refund hash. readOnly: true deposit_id: type: - string - 'null' title: deposit_id readOnly: true failure_details: $ref: '#/components/schemas/bastion.api.v2.conversions.RefundFailureDetails' title: failure_details readOnly: true title: RefundDetails additionalProperties: false bastion.api.v2.conversions.PaymentMethod: type: string title: PaymentMethod enum: - PAYMENT_METHOD_UNSPECIFIED - BLOCKCHAIN - WIRE - SPEI - IMPS_FIRC - BANK_TRANSFER - SEPA description: Transfer mechanism for the conversion. example: BLOCKCHAIN bastion.common.Chain: type: string title: Chain enum: - CHAIN_UNSPECIFIED - ETHEREUM_MAINNET - POLYGON_MAINNET - ETHEREUM_TESTNET - OPTIMISM_SEPOLIA - BASE_MAINNET - BASE_SEPOLIA - OPTIMISM_MAINNET - POLYGON_AMOY - SOLANA_MAINNET - SOLANA_DEVNET description: Chain identifier example: ETHEREUM_MAINNET bastion.common.Country: type: string title: Country enum: - US description: ISO 3166-1 alpha-2 country code. example: US bastion.common.FeeType: type: string title: FeeType enum: - FEE_TYPE_UNSPECIFIED - PLATFORM - DEVELOPER description: Type of fee charged on a conversion. example: PLATFORM bastion.api.v2.conversions.RefundFailureDetails: type: object properties: type: $ref: '#/components/schemas/bastion.api.v2.conversions.RefundFailureType' title: type readOnly: true description: type: - string - 'null' title: description readOnly: true title: RefundFailureDetails additionalProperties: false bastion.api.v2.conversions.RefundFailureType: type: string title: RefundFailureType enum: - REFUND_FAILURE_TYPE_UNSPECIFIED - REFUND_FAILURE_TYPE_BANK_REJECTED - REFUND_FAILURE_TYPE_EXPIRED - REFUND_FAILURE_TYPE_DATA_MISSING - REFUND_FAILURE_TYPE_OTHER - REFUND_FAILURE_TYPE_PAYOUT_RETURNED description: Structured failure category on RETURNED conversions. example: REFUND_FAILURE_TYPE_BANK_REJECTED securitySchemes: auth: type: http description: Bearer authentication with an API token scheme: bearer ```` ## Related topics - [Sandbox vs. production environments](/guides/getting-started/sandbox-vs-production-environments.md) - [Off-ramp: Withdraw stablecoin to a bank account](/guides/quickstarts/off-ramp.md) - [Off-ramp: Withdraw stablecoin internationally](/guides/quickstarts/off-ramp/international-bank-account.md) - [Off-ramp: Withdraw stablecoin to a US bank account](/guides/quickstarts/off-ramp/withdraw-to-a-bank-account.md) - [Conversion notifications](/v2/api-reference/webhooks/notifications/conversions-notifications.md)