> ## Documentation Index > Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt > Use this file to discover all available pages before exploring further. # Create an On-Ramp or Off-Ramp Transfer > Create a new transfer. Use this endpoint to initiate a money movement for a verified customer. SpherePay supports two transfer directions: **on-ramp** (fiat → crypto) and **off-ramp** (crypto → fiat). You define the direction by the types you supply for `source` and `destination` — a `bank_account` source with a `wallet` destination creates an on-ramp, and the reverse creates an off-ramp. The response includes deposit instructions your customer needs to fund the transfer. The customer must have an `approved` verification profile before you can create a transfer on their behalf. ## OpenAPI ````yaml openapi/spherepay.yaml POST /v2/transfer openapi: 3.0.0 info: contact: {} description: The Sphere REST API for payments, transfers, and accounts. title: Sphere API version: '2' servers: - description: Production url: https://api.spherepay.co security: - bearer: [] tags: [] paths: /v2/transfer: post: summary: Create a Transfer description: Create a new transfer. operationId: postV2Transfer parameters: [] requestBody: content: application/json: schema: oneOf: - properties: customer: description: The customer's ID. example: customer_1234567890 pattern: ^customer_[a-z0-9]+$ type: string destination: properties: id: description: The payment instrument ID (wallet or bank account). example: wallet_1234567890abcdef1234567890abcdef12345678 type: string type: description: 'The payment instrument type: wallet or bank_account.' enum: - bank_account - wallet example: wallet type: string required: - type - id type: object documentId: description: >- ID of a pre-uploaded supporting document (from POST /v2/document with target `transfer`). Required for third-party transfers on certain routes. A transfer is considered third-party when the destination bank account owner is not the customer themselves (i.e. the bank account relationship is not `self`). The document should evidence the purpose of the transfer - for example, an invoice, contract, payment agreement, or proof of services rendered. example: document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 minLength: 1 pattern: ^document_[a-z0-9]+$ type: string externalId: description: >- Integrator-defined external reference. The value is not stored as unique. example: merchant_ref_123 type: string paymentDescription: description: >- A free-text description of the payment purpose. Required for third-party off-ramp transfers (where the destination bank account owner relationship is not `self`). Max 500 characters. example: INV-2026-004 - Q1 software services maxLength: 500 minLength: 1 type: string paymentReason: description: >- The reason for the payment. Required for SWIFT transfers, BRL transfers, and for third-party off-ramp transfers (where the destination bank account owner relationship is not `self`). enum: - personal - investment - real_estate - tax - loan - bills - reimbursement - professional_services - family_support - education - rent - donation - gift - insurance - medical - savings - travel - mortgage - fine - dividend - agriculture - import_export - art - other example: professional_services type: string quoteId: description: >- The quote ID from a previously created quote. The transfer uses the locked exchange rate, currency, and network from the quote. example: quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string source: properties: id: description: The payment instrument ID (wallet or bank account). example: wallet_1234567890abcdef1234567890abcdef12345678 type: string type: description: 'The payment instrument type: wallet or bank_account.' enum: - bank_account - wallet example: wallet type: string required: - type - id type: object required: - customer - quoteId - source - destination title: Transfer with Quote type: object - description: >- Standard floating-rate transfer. For BRL (PIX) transfers: only `polygon`, `ethereum`, `base`, and `tron` wallet networks are supported (not `sol`); `integratorFixedFee` is not allowed - use `integratorBpsFeeRate` instead. See [BRL/PIX transfer constraints](/concepts/transfers/overview#brlpix-transfer-constraints) for current transfer limits. properties: amount: description: >- The transfer amount in source currency. Must have exactly 2 decimal places. Transfer limits are set dynamically based on due diligence and may change over time - see [BRL/PIX transfer constraints](/concepts/transfers/overview#brlpix-transfer-constraints) for current BRL limits. example: '100.00' type: string customer: description: The customer's ID. example: customer_1234567890 pattern: ^customer_[a-z0-9]+$ type: string destination: oneOf: - description: >- The destination of an `On-ramp` transfer. See [Wallets](/concepts/transfers/wallets) for registration. properties: currency: description: >- The destination currency for an `On-ramp` transfer. This should be the currency of the wallet. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string id: description: The destination wallet ID. example: wallet_1234567890abcdef1234567890abcdef12345678 pattern: ^wallet_[a-z0-9]+$ type: string network: description: >- The destination network of the customer's wallet. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - ethereum - arbitrum - polygon - base - avalanche - tron example: sol type: string type: description: 'The destination type: wallet.' enum: - wallet example: wallet type: string required: - type - id - currency - network title: Destination Wallet type: object - description: The destination bank account for transfers. properties: achReference: description: >- Reference sent to the receiving institution with ACH transfers, 1-10 characters. example: REF123 maxLength: 10 minLength: 1 type: string currency: description: >- The destination currency: [usd, eur, brl, mxn]. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usd - eur - brl example: usd type: string id: description: The destination bank account ID. example: bank_account_123abc... type: string network: description: >- The destination network: [wire, ach, achPush, achPull, achSameDay, swift, sepa, pix, spei]. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - ach - wire - sepa - pix - swift example: ach type: string sepaReference: description: >- Reference sent to the receiving institution with SEPA transfers, 6-140 characters. example: INV-2024-001 maxLength: 140 minLength: 6 type: string type: description: 'The destination type: bank_account.' enum: - bank_account example: bank_account type: string wireMessage: description: >- Message sent to the receiving institution with wire transfers, 1-105 characters. example: 'Invoice #1024' maxLength: 105 minLength: 1 type: string required: - type - id - currency - network title: Destination Bank Account type: object documentId: description: >- ID of a pre-uploaded supporting document (from POST /v2/document with target `transfer`). Required for third-party transfers on certain routes. A transfer is considered third-party when the destination bank account owner is not the customer themselves (i.e. the bank account relationship is not `self`). The document should evidence the purpose of the transfer - for example, an invoice, contract, payment agreement, or proof of services rendered. example: document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 minLength: 1 pattern: ^document_[a-z0-9]+$ type: string externalId: description: >- Integrator-defined external reference. The value is not stored as unique. example: merchant_ref_123 type: string integratorBpsFeeRate: description: >- The integrator BPS fee rate as an integer string (1 bps = 0.01%). This is the only fee mechanism supported for BRL transfers. example: '20' pattern: ^\d+$ type: string integratorFixedFee: description: >- The integrator fixed fee amount in source currency. Must have exactly 2 decimal places. Not supported for BRL transfers - use integratorBpsFeeRate instead. example: '2.00' type: string paymentDescription: description: >- A free-text description of the payment purpose. Required for third-party off-ramp transfers (where the destination bank account owner relationship is not `self`). Max 500 characters. example: INV-2026-004 - Q1 software services maxLength: 500 minLength: 1 type: string paymentReason: description: >- The reason for the payment. Required for SWIFT transfers, BRL transfers, and for third-party off-ramp transfers (where the destination bank account owner relationship is not `self`). enum: - personal - investment - real_estate - tax - loan - bills - reimbursement - professional_services - family_support - education - rent - donation - gift - insurance - medical - savings - travel - mortgage - fine - dividend - agriculture - import_export - art - other example: professional_services type: string source: oneOf: - description: >- The source of an `Off-ramp` transfer. See [Wallets](/concepts/transfers/wallets) for registration. properties: currency: description: >- The source currency for an `Off-ramp` transfer. This should be the currency of the wallet. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string id: description: The source wallet ID. example: wallet_1234567890abcdef1234567890abcdef12345678 pattern: ^wallet_[a-z0-9]+$ type: string network: description: >- The source network of the customer's wallet. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - ethereum - arbitrum - polygon - base - avalanche - tron example: sol type: string type: description: 'The source type: wallet.' enum: - wallet example: wallet type: string required: - type - id - currency - network title: Source Wallet type: object - description: The source of an `On-ramp` transfer. properties: currency: description: >- The source currency for an `On-ramp` transfer. This should be the currency of the bank account. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usd - eur - brl - mxn example: usd type: string id: description: The source bank account ID. example: bank_account_1234567890 pattern: ^bankAccount_[a-z0-9]+$ type: string network: description: >- The source network of the bank account. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - ach - wire - sepa - pix - swift - spei example: ach type: string type: description: 'The source type: bank_account.' enum: - bank_account example: bank_account type: string required: - type - id - currency - network title: Source Bank Account type: object required: - amount - customer - source - destination title: Transfer type: object required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CreateTransferResponseDto' description: '' '400': content: application/json: examples: Bad Request: summary: Bad Request value: code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Invalid request parameters status: 400 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Bad Request '404': content: application/json: examples: Not Found: summary: Not Found value: code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Resource not found status: 404 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Not Found '422': content: application/json: examples: Validation Error: summary: Validation Error value: code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c detail: Validation failed errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name status: 422 schema: $ref: '#/components/schemas/ProblemDetailsDto' description: Unprocessable Entity - Validation Error components: schemas: CreateTransferResponseDto: properties: created: description: The datetime the transfer was created. example: '2021-01-01T00:00:00.000Z' format: date-time type: string customer: description: The customer ID. example: customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7 type: string depositAccount: oneOf: - description: The deposit bank account for an on ramp transfer. properties: bankDetails: properties: accountHolderName: description: >- The name of the bank account holder that the source funds will be transferred to. example: John Doe type: string accountNumber: description: >- The account number of the bank account, used for wires, ACH transfers and other applicable networks. example: '1234567890' type: string accountType: description: 'The type of bank account: savings or checking.' enum: - savings - checking example: savings type: string bankAddress: description: The address of the deposit bank account. example: 123 Main St, Anytown, USA type: string bankName: description: >- The name of the bank that the source funds will be transferred to. example: Bank of America type: string beneficiaryAddress: description: >- The address of the beneficiary that will receive the funds. example: 123 Main St, Anytown, USA type: string bic: description: >- The BIC of the bank account, used for SEPA transfers and other applicable networks. example: '1234567890' type: string brCode: description: >- The PIX BR code for on-ramp payments. Encode this as a QR code for the customer to scan and pay. example: >- 00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string clabe: description: >- The CLABE of the deposit bank account, used for SPEI transfers in Mexico. example: '012345678901234567' type: string iban: description: >- The IBAN of the bank account, used for SEPA transfers and other applicable networks. example: '1234567890' type: string memo: description: >- The memo of the transfer. This must be provided when initiating wire, ACH and SEPA transfers. This is the memo that will be used to identify the transfer to the deposit account. example: BBE6C7EB4A3F type: string pixKey: description: >- The PIX key of the deposit bank account, used for PIX transfers. example: '+5511999999999' type: string routingNumber: description: >- The routing number of the bank account, used for wires, ACH transfers and other applicable networks. example: '1234567890' type: string type: object type: description: The type of the deposit account. enum: - bank_account example: bank_account type: string required: - type - bankDetails title: Deposit Bank Account type: object - description: The deposit wallet for an off ramp transfer. properties: type: description: The type of the deposit account. enum: - wallet example: wallet type: string walletDetails: properties: address: description: >- The address of the wallet that the source funds will be transferred to. example: '0x1234567890abcdef1234567890abcdef12345678' type: string currency: description: >- The currency that should be transferred to the wallet. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string network: description: >- The network that the source funds will be transferred on. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: ethereum type: string required: - address - currency - network type: object required: - type - walletDetails title: Deposit Wallet type: object destination: oneOf: - description: >- The destination of an `On-ramp` transfer. See [Wallets](/concepts/transfers/wallets) for registration. properties: amount: type: string currency: description: >- The destination wallet currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string exchangeRate: description: >- The exchange rate applied to the destination amount when converting the source amount to the destination currency. example: '5.455' type: string id: description: The destination wallet ID. example: wallet_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2 pattern: ^wallet_[a-z0-9]+$ type: string network: description: >- The destination wallet network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: sol type: string type: description: The destination wallet type. enum: - wallet example: wallet type: string required: - id - type - currency - network title: Destination Wallet type: object - description: The destination of an `Off-ramp` transfer. properties: achReference: description: The ACH reference string. example: ABC123456789 type: string amount: description: >- The destination amount being transferred to the bank account. example: '98.90' type: string currency: description: >- The destination bank account currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usd - eur - brl - mxn example: usd type: string exchangeRate: description: >- The exchange rate applied to the destination amount when converting the source amount to the destination currency. example: '5.455' type: string id: description: The destination bank account ID. example: bankAccount_f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3 pattern: ^bankAccount_[a-z0-9]+$ type: string network: description: >- The destination bank account network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - ach - wire - sepa - pix - swift - spei example: wire type: string sepaReference: description: The SEPA reference string. example: ABC123456789 type: string type: description: The destination account type. enum: - bank_account example: bank_account type: string wireMessage: description: The message included with the wire transfer. example: Payment for invoice 12345 type: string required: - id - type - currency - network title: Destination Bank Account type: object externalId: description: The external reference (not stored as unique). example: merchant_ref_123 type: string fees: description: >- Fee breakdown for the transfer. For floating-rate BRL transfers, this is omitted until settlement is complete. properties: integratorFee: description: >- The integrator fee, this is the portion of the fee that the API integrator will receive. example: bpsAmount: '0.10' bpsRate: '10' currency: usd fixedAmount: '1.00' totalAmount: '1.10' properties: bpsAmount: description: >- The dollar amount derived from the BPS rate. Equal to totalAmount minus fixedAmount. example: '0.10' type: string bpsRate: description: The BPS rate of the fee. example: '10' type: string currency: description: >- The currency of the fee. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc - usd - eur - brl - mxn example: usd type: string fixedAmount: description: The fixed amount of the fee. example: '1.00' type: string totalAmount: description: The total amount of the fee applied to the source amount. example: '1.10' type: string required: - fixedAmount - bpsRate - bpsAmount - totalAmount - currency type: object platformFee: description: >- The platform fee, this is the portion of the fee that Sphere will receive. example: bpsAmount: '0.10' bpsRate: '10' currency: usd fixedAmount: '2.00' totalAmount: '2.10' properties: bpsAmount: description: >- The dollar amount derived from the BPS rate. Equal to totalAmount minus fixedAmount. example: '0.10' type: string bpsRate: description: The BPS rate of the fee. example: '10' type: string currency: description: >- The currency of the fee. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc - usd - eur - brl - mxn example: usd type: string fixedAmount: description: The fixed amount of the fee. example: '1.00' type: string totalAmount: description: The total amount of the fee applied to the source amount. example: '1.10' type: string required: - fixedAmount - bpsRate - bpsAmount - totalAmount - currency type: object required: - integratorFee - platformFee type: object id: description: A unique identifier for transfer. example: payout_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 pattern: ^payout_[a-z0-9]{32}$ type: string paymentDescription: description: >- A free-text description of the payment purpose. Present on third-party off-ramp transfers. example: INV-2026-004 - Q1 software services type: string paymentReason: description: >- The reason for the payment. Present on BRL transfers and third-party off-ramp transfers. example: professional_services type: string quote: description: >- The quote used for this transfer, if any. When present, the locked exchange rate from the quote was applied to the destination amount and exchange rate. properties: expiresAt: description: The datetime the quote expires. example: '2021-01-01T00:00:00.000Z' format: date-time type: string id: description: The unique identifier for the quote used for this transfer. example: quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string required: - id - expiresAt type: object source: oneOf: - description: The source of an on ramp transfer. example: id: bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: bank_account properties: achReference: description: The ACH reference string. example: ABC123456789 type: string amount: description: >- The source amount being transferred out of the source bank account. example: '100.00' type: string currency: description: >- The source bank account currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usd - eur - brl - mxn example: usd type: string id: description: The source bank account ID. example: bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 pattern: ^bankAccount_[a-z0-9]+$ type: string network: description: >- The source bank account network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - ach - wire - sepa - pix - swift - spei example: wire type: string sepaReference: description: The SEPA reference string. example: ABC123456789 type: string type: description: The source account type. enum: - bank_account example: bank_account type: string wireMessage: description: The message included with the wire transfer. example: Payment for invoice 12345 type: string required: - id - type - currency - network - amount title: Source Bank Account type: object - description: >- The source of an off ramp transfer. See [Wallets](/concepts/transfers/wallets) for registration. properties: amount: description: >- The source amount being transferred out of the source wallet. example: '100.00' type: string currency: description: >- The source wallet currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - usdc - usdt - eurc example: usdc type: string id: description: The source wallet ID. example: wallet_d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1 pattern: ^wallet_[a-z0-9]+$ type: string network: description: >- The source wallet network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails). enum: - sol - fogo - ethereum - arbitrum - polygon - base - avalanche - sui - noble - sei - tron - starknet - aptos - hyperliquid example: sol type: string type: description: The source type. enum: - wallet example: wallet type: string required: - id - type - currency - network - amount title: Source Wallet type: object status: description: >- The transfer status. See [Transfer Lifecycle](/concepts/transfers/lifecycle) for status definitions and transitions. enum: - pendingFunding - pendingReview - fundsReceived - processing - succeeded - undeliverable - returned - pendingRefundInformation - failed - canceled - refunded - unexpectedError - failedPrecondition - expired - unfunded example: pendingFunding type: string x-enumNames: - PENDING_FUNDING - PENDING_REVIEW - FUNDS_RECEIVED - PROCESSING - SUCCEEDED - UNDELIVERABLE - RETURNED - PENDING_REFUND_INFO - FAILED - CANCELED - REFUNDED - UNEXPECTED_ERROR - FAILED_PRECONDITION - EXPIRED - UNFUNDED statusHistory: description: >- Timeline of status transitions for this transfer, ascending by transitionedAt. example: - status: pendingFunding transitionedAt: '2026-06-20T14:03:21.000Z' - status: processing transitionedAt: '2026-06-20T14:05:10.000Z' items: description: A single transfer status transition. properties: status: enum: - pendingFunding - pendingReview - fundsReceived - processing - succeeded - undeliverable - returned - pendingRefundInformation - failed - canceled - refunded - unexpectedError - failedPrecondition - expired - unfunded type: string x-enumNames: - PENDING_FUNDING - PENDING_REVIEW - FUNDS_RECEIVED - PROCESSING - SUCCEEDED - UNDELIVERABLE - RETURNED - PENDING_REFUND_INFO - FAILED - CANCELED - REFUNDED - UNEXPECTED_ERROR - FAILED_PRECONDITION - EXPIRED - UNFUNDED transitionedAt: description: ISO 8601 timestamp of when the transfer entered this status. example: '2026-06-20T14:05:10.000Z' format: date-time type: string required: - status - transitionedAt title: Transfer Status History Entry type: object type: array type: description: The transfer type. enum: - on_ramp - off_ramp - fiat_to_fiat - unmatched_deposit - microdeposit example: on_ramp type: string updated: description: The last datetime the transfer was updated. example: '2021-01-01T00:00:00.000Z' format: date-time type: string required: - id - type - status - statusHistory - customer - source - destination - depositAccount - updated - created type: object ProblemDetailsDto: properties: code: type: string correlationId: type: string detail: type: string errors: items: properties: detail: type: string header: type: string parameter: type: string pointer: type: string required: - detail type: object type: array status: type: integer title: type: string required: - status - detail type: object securitySchemes: bearer: bearerFormat: JWT scheme: bearer type: http ````