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

# Ruby SDK Reference

> Complete reference for the Devdraft Ruby SDK with all available methods and examples

## Overview

The Devdraft Ruby SDK provides a complete client library for integrating payment processing, customer management, and webhook functionality into your Ruby applications.

<CardGroup cols={2}>
  <Card title="Ruby Idioms" icon="gem">
    Follows Ruby conventions with blocks, symbols, and elegant syntax
  </Card>

  <Card title="Gem Package" icon="box">
    Easy installation via RubyGems package manager
  </Card>

  <Card title="Comprehensive" icon="boxes-stacked">
    Access to all Devdraft API endpoints and features
  </Card>

  <Card title="Rails Compatible" icon="code">
    Works seamlessly with Ruby on Rails applications
  </Card>
</CardGroup>

## Installation

### Using Bundler

Add to your `Gemfile`:

```ruby theme={null}
gem 'devdraft', '~> 1.0.0'
```

Then run:

```bash theme={null}
bundle install
```

### Using RubyGems

```bash theme={null}
gem install devdraft
```

### Install from Source

```bash theme={null}
gem build devdraft.gemspec
gem install ./devdraft-1.0.0.gem
```

## Requirements

* Ruby 2.7 or higher

## Quick Start

```ruby theme={null}
require 'devdraft'

# Configure API credentials
Devdraft.configure do |config|
  config.api_key['x-client-key'] = ENV['DEVDRAFT_CLIENT_KEY']
  config.api_key['x-client-secret'] = ENV['DEVDRAFT_CLIENT_SECRET']
  config.server_index = nil
  config.base_url = 'https://api.devdraft.ai'
end

# Create API instances
transfers_api = Devdraft::TransfersApi.new
webhooks_api = Devdraft::WebhooksApi.new

begin
  # Create a transfer
  transfer_dto = Devdraft::CreateDirectWalletTransferDto.new(
    wallet_id: 'your-wallet-id',
    network: 'solana',
    stable_coin_currency: 'usdc',
    amount: 100.00
  )
  
  transfer = transfers_api.transfer_controller_create_direct_wallet_transfer(transfer_dto)
  puts "Transfer created: #{transfer.id}"
rescue Devdraft::ApiError => e
  puts "Error: #{e.message}"
end
```

## API Classes

The SDK is organized into API classes under the `Devdraft` module:

| API Class                                         | Description                                     |
| ------------------------------------------------- | ----------------------------------------------- |
| [APIHealthApi](#api-health)                       | Service health checks and status monitoring     |
| [AppBalancesApi](#app-balances)                   | Query application balances across stablecoins   |
| [CustomersApi](#customers)                        | Customer management and KYC operations          |
| [ExchangeRatesApi](#exchange-rates)               | Real-time currency exchange rates               |
| [InvoicesApi](#invoices)                          | Invoice creation and management                 |
| [LiquidationAddressesApi](#liquidation-addresses) | Cryptocurrency liquidation addresses            |
| [PaymentIntentsApi](#payment-intents)             | Payment intent creation for bank and stablecoin |
| [PaymentLinksApi](#payment-links)                 | Generate and manage payment links               |
| [ProductsApi](#products)                          | Product catalog management                      |
| [TaxesApi](#taxes)                                | Tax configuration and management                |
| [TestPaymentsApi](#test-payments)                 | Test payment processing in sandbox              |
| [TransfersApi](#transfers)                        | Initiate and manage fund transfers              |
| [WalletsApi](#wallets)                            | Wallet management and balances                  |
| [WebhooksApi](#webhooks)                          | Webhook configuration and management            |

***

## API Health

Monitor service health and availability.

### Methods

#### `health_controller_check_v0()`

Authenticated health check endpoint requiring API credentials.

```ruby theme={null}
require 'devdraft'

Devdraft.configure do |config|
  config.api_key['x-client-key'] = ENV['DEVDRAFT_CLIENT_KEY']
  config.api_key['x-client-secret'] = ENV['DEVDRAFT_CLIENT_SECRET']
end

api_instance = Devdraft::APIHealthApi.new

begin
  api_instance.health_controller_check_v0
  puts 'Service is healthy and authenticated'
rescue Devdraft::ApiError => e
  puts "Health check failed: #{e}"
end
```

**Returns:** `nil`

#### `health_controller_public_health_check_v0()`

Public health check endpoint (no authentication required).

```ruby theme={null}
status = api_instance.health_controller_public_health_check_v0
puts "Service status: #{status.status}"
```

**Returns:** `PublicHealthResponseDto`

***

## App Balances

Query your application's stablecoin balances.

### Methods

#### `balance_controller_get_all_balances()`

Get all stablecoin balances for your application.

```ruby theme={null}
require 'devdraft'

api_instance = Devdraft::AppBalancesApi.new

begin
  balances = api_instance.balance_controller_get_all_balances
  puts "USDC Balance: #{balances.usdc}"
  puts "EURC Balance: #{balances.eurc}"
rescue Devdraft::ApiError => e
  puts "Error: #{e}"
end
```

**Returns:** `AllBalancesResponse`

#### `balance_controller_get_usdc_balance()`

Get USDC balance only.

```ruby theme={null}
usdc_balance = api_instance.balance_controller_get_usdc_balance
puts "USDC: #{usdc_balance.amount}"
```

**Returns:** `AggregatedBalanceResponse`

#### `balance_controller_get_eurc_balance()`

Get EURC balance only.

```ruby theme={null}
eurc_balance = api_instance.balance_controller_get_eurc_balance
puts "EURC: #{eurc_balance.amount}"
```

**Returns:** `AggregatedBalanceResponse`

***

## Customers

Manage customer records and KYC information.

### Methods

#### `customer_controller_create(create_customer_dto)`

Create a new customer.

```ruby theme={null}
require 'devdraft'

api_instance = Devdraft::CustomersApi.new

begin
  customer_dto = Devdraft::CreateCustomerDto.new(
    first_name: 'John',
    last_name: 'Doe',
    email: 'john.doe@example.com',
    type: 'INDIVIDUAL',
    country: 'US'
  )
  
  customer = api_instance.customer_controller_create(customer_dto)
  puts "Customer created: #{customer.id}"
rescue Devdraft::ApiError => e
  puts "Error: #{e}"
end
```

**Parameters:**

* `create_customer_dto: CreateCustomerDto` - Customer details

**Returns:** `Customer`

#### `customer_controller_find_all(opts = {})`

Get all customers with optional filters.

```ruby theme={null}
opts = {
  page: 1,
  limit: 20,
  status: 'ACTIVE'
}

customers = api_instance.customer_controller_find_all(opts)

customers.each do |customer|
  puts "#{customer.first_name} #{customer.last_name} - #{customer.email}"
end
```

**Parameters:**

* `opts: Hash` - Optional parameters
  * `page: Integer` - Page number (default: 1)
  * `limit: Integer` - Items per page (default: 20)
  * `status: String` - Filter by status

**Returns:** `Array<Customer>`

#### `customer_controller_find_one(id)`

Get a customer by ID.

```ruby theme={null}
customer = api_instance.customer_controller_find_one('customer-id-here')
puts "Customer: #{customer.first_name} #{customer.last_name}"
```

**Parameters:**

* `id: String` - Customer ID

**Returns:** `Customer`

#### `customer_controller_update(id, update_customer_dto)`

Update a customer's information.

```ruby theme={null}
update_dto = Devdraft::UpdateCustomerDto.new(
  phone: '+1234567890',
  address: '123 Main St'
)

updated = api_instance.customer_controller_update('customer-id-here', update_dto)
puts "Customer updated: #{updated.id}"
```

**Parameters:**

* `id: String` - Customer ID
* `update_customer_dto: UpdateCustomerDto` - Fields to update

**Returns:** `Customer`

***

## Exchange Rates

Get real-time currency exchange rates.

### Methods

#### `exchange_rate_controller_get_exchange_rate(opts = {})`

Get exchange rate between any two supported currencies.

```ruby theme={null}
require 'devdraft'

api_instance = Devdraft::ExchangeRatesApi.new

begin
  opts = {
    from: 'USD',
    to: 'EUR'
  }
  
  rate = api_instance.exchange_rate_controller_get_exchange_rate(opts)
  puts "1 USD = #{rate.rate} EUR"
  puts "Rate expires at: #{rate.expires_at}"
rescue Devdraft::ApiError => e
  puts "Error: #{e}"
end
```

**Parameters:**

* `opts: Hash` - Optional parameters
  * `from: String` - Source currency code
  * `to: String` - Target currency code

**Returns:** `ExchangeRateResponseDto`

#### `exchange_rate_controller_get_usdto_eur_rate()`

Get USD to EUR exchange rate.

```ruby theme={null}
usd_to_eur = api_instance.exchange_rate_controller_get_usdto_eur_rate
puts "USD to EUR: #{usd_to_eur.rate}"
```

**Returns:** `ExchangeRateResponseDto`

#### `exchange_rate_controller_get_eurto_usd_rate()`

Get EUR to USD exchange rate.

```ruby theme={null}
eur_to_usd = api_instance.exchange_rate_controller_get_eurto_usd_rate
puts "EUR to USD: #{eur_to_usd.rate}"
```

**Returns:** `ExchangeRateResponseDto`

***

## Invoices

Create and manage invoices for your customers.

### Methods

#### `invoice_controller_create(create_invoice_dto)`

Create a new invoice.

```ruby theme={null}
require 'devdraft'

api_instance = Devdraft::InvoicesApi.new

begin
  invoice_dto = Devdraft::CreateInvoiceDto.new(
    customer_id: 'customer-id',
    items: [
      {
        description: 'Premium Subscription',
        quantity: 1,
        price: 99.99,
        currency: 'USD'
      }
    ],
    due_date: '2024-12-31'
  )
  
  invoice = api_instance.invoice_controller_create(invoice_dto)
  puts "Invoice created: #{invoice.id}"
  puts "Total: #{invoice.total}"
rescue Devdraft::ApiError => e
  puts "Error: #{e}"
end
```

**Parameters:**

* `create_invoice_dto: CreateInvoiceDto` - Invoice details

**Returns:** `Invoice`

#### `invoice_controller_find_all(opts = {})`

Get all invoices.

```ruby theme={null}
opts = {
  page: 1,
  limit: 50,
  status: 'UNPAID'
}

invoices = api_instance.invoice_controller_find_all(opts)

invoices.each do |invoice|
  puts "Invoice #{invoice.id}: #{invoice.total}"
end
```

**Parameters:**

* `opts: Hash` - Optional parameters
  * `page: Integer` - Page number
  * `limit: Integer` - Items per page
  * `status: String` - Filter by status

**Returns:** `Array<Invoice>`

#### `invoice_controller_find_one(id)`

Get an invoice by ID.

```ruby theme={null}
invoice = api_instance.invoice_controller_find_one('invoice-id')
puts "Invoice total: #{invoice.total}"
```

**Parameters:**

* `id: String` - Invoice ID

**Returns:** `Invoice`

#### `invoice_controller_update(id, update_invoice_dto)`

Update an invoice.

```ruby theme={null}
update_dto = {
  status: 'PAID',
  paid_at: Time.now.iso8601
}

updated = api_instance.invoice_controller_update('invoice-id', update_dto)
puts "Invoice updated: #{updated.id}"
```

**Parameters:**

* `id: String` - Invoice ID
* `update_invoice_dto: Hash` - Fields to update

**Returns:** `Invoice`

***

## Liquidation Addresses

Manage cryptocurrency liquidation addresses for customers.

### Methods

#### `liquidation_address_controller_create_liquidation_address(customer_id, create_liquidation_address_dto)`

Create a new liquidation address for a customer.

```ruby theme={null}
require 'devdraft'

api_instance = Devdraft::LiquidationAddressesApi.new

begin
  address_dto = Devdraft::CreateLiquidationAddressDto.new(
    network: 'solana',
    currency: 'usdc'
  )
  
  address = api_instance.liquidation_address_controller_create_liquidation_address(
    'customer-id',
    address_dto
  )
  
  puts "Liquidation address: #{address.address}"
  puts "Network: #{address.network}"
rescue Devdraft::ApiError => e
  puts "Error: #{e}"
end
```

**Parameters:**

* `customer_id: String` - Customer ID
* `create_liquidation_address_dto: CreateLiquidationAddressDto` - Address details

**Returns:** `LiquidationAddressResponseDto`

#### `liquidation_address_controller_get_liquidation_addresses(customer_id)`

Get all liquidation addresses for a customer.

```ruby theme={null}
addresses = api_instance.liquidation_address_controller_get_liquidation_addresses('customer-id')

addresses.each do |addr|
  puts "#{addr.network}: #{addr.address}"
end
```

**Parameters:**

* `customer_id: String` - Customer ID

**Returns:** `Array<LiquidationAddressResponseDto>`

#### `liquidation_address_controller_get_liquidation_address(customer_id, liquidation_address_id)`

Get a specific liquidation address.

```ruby theme={null}
address = api_instance.liquidation_address_controller_get_liquidation_address(
  'customer-id',
  'address-id'
)

puts "Address: #{address.address}"
```

**Parameters:**

* `customer_id: String` - Customer ID
* `liquidation_address_id: String` - Address ID

**Returns:** `LiquidationAddressResponseDto`

***

## Payment Intents

Create payment intents for bank and stablecoin payments.

### Methods

#### `payment_intent_controller_create_bank_payment_intent(create_bank_payment_intent_dto)`

Create a bank payment intent.

```ruby theme={null}
require 'devdraft'

api_instance = Devdraft::PaymentIntentsApi.new

begin
  intent_dto = Devdraft::CreateBankPaymentIntentDto.new(
    customer_id: 'customer-id',
    amount: 1000.00,
    currency: 'USD',
    payment_rail: 'wire'
  )
  
  intent = api_instance.payment_intent_controller_create_bank_payment_intent(intent_dto)
  puts "Payment intent: #{intent.id}"
  puts "Status: #{intent.status}"
rescue Devdraft::ApiError => e
  puts "Error: #{e}"
end
```

**Parameters:**

* `create_bank_payment_intent_dto: CreateBankPaymentIntentDto` - Intent details

**Returns:** `PaymentIntent`

#### `payment_intent_controller_create_stable_payment_intent(create_stable_payment_intent_dto)`

Create a stablecoin payment intent.

```ruby theme={null}
stable_intent_dto = Devdraft::CreateStablePaymentIntentDto.new(
  customer_id: 'customer-id',
  amount: 500.00,
  currency: 'usdc',
  network: 'solana'
)

stable_intent = api_instance.payment_intent_controller_create_stable_payment_intent(stable_intent_dto)
puts "Stable intent: #{stable_intent.id}"
```

**Parameters:**

* `create_stable_payment_intent_dto: CreateStablePaymentIntentDto` - Intent details

**Returns:** `PaymentIntent`

***

## Payment Links

Generate and manage payment links for easy customer payments.

### Methods

#### `payment_links_controller_create(create_payment_link_dto)`

Create a new payment link.

```ruby theme={null}
require 'devdraft'

api_instance = Devdraft::PaymentLinksApi.new

begin
  link_dto = Devdraft::CreatePaymentLinkDto.new(
    name: 'Product Purchase',
    amount: 99.99,
    currency: 'USD',
    products: [
      {
        name: 'Premium Plan',
        quantity: 1,
        price: 99.99
      }
    ]
  )
  
  link = api_instance.payment_links_controller_create(link_dto)
  puts "Payment link: #{link.url}"
  puts "Share this link with customers: #{link.short_url}"
rescue Devdraft::ApiError => e
  puts "Error: #{e}"
end
```

**Parameters:**

* `create_payment_link_dto: CreatePaymentLinkDto` - Link details

**Returns:** `PaymentLink`

#### `payment_links_controller_find_all(opts = {})`

Get all payment links.

```ruby theme={null}
opts = {
  page: 1,
  limit: 20,
  active: true
}

links = api_instance.payment_links_controller_find_all(opts)

links.each do |link|
  puts "#{link.name}: #{link.url}"
end
```

**Parameters:**

* `opts: Hash` - Optional parameters
  * `page: Integer` - Page number
  * `limit: Integer` - Items per page
  * `active: Boolean` - Filter by active status

**Returns:** `Array<PaymentLink>`

#### `payment_links_controller_find_one(id)`

Get a payment link by ID.

```ruby theme={null}
link = api_instance.payment_links_controller_find_one('link-id')
puts "Link: #{link.url}"
```

**Parameters:**

* `id: String` - Payment link ID

**Returns:** `PaymentLink`

#### `payment_links_controller_update(id, update_payment_link_dto)`

Update a payment link.

```ruby theme={null}
update_dto = {
  active: false,
  expires_at: '2024-12-31T23:59:59Z'
}

updated = api_instance.payment_links_controller_update('link-id', update_dto)
puts "Link updated: #{updated.id}"
```

**Parameters:**

* `id: String` - Payment link ID
* `update_payment_link_dto: Hash` - Fields to update

**Returns:** `PaymentLink`

***

## Products

Manage your product catalog.

### Methods

#### `product_controller_create(create_product_dto)`

Create a new product.

```ruby theme={null}
require 'devdraft'

api_instance = Devdraft::ProductsApi.new

begin
  product_dto = {
    name: 'Premium Subscription',
    description: 'Access to all premium features',
    price: 99.99,
    currency: 'USD',
    category: 'subscriptions'
  }
  
  product = api_instance.product_controller_create(product_dto)
  puts "Product created: #{product.id}"
rescue Devdraft::ApiError => e
  puts "Error: #{e}"
end
```

**Parameters:**

* `create_product_dto: Hash` - Product details

**Returns:** `Product`

#### `product_controller_find_all(opts = {})`

Get all products.

```ruby theme={null}
opts = {
  category: 'subscriptions',
  active: true
}

products = api_instance.product_controller_find_all(opts)

products.each do |product|
  puts "#{product.name}: $#{product.price}"
end
```

**Parameters:**

* `opts: Hash` - Optional parameters
  * `category: String` - Filter by category
  * `active: Boolean` - Filter by active status

**Returns:** `Array<Product>`

#### `product_controller_find_one(id)`

Get a product by ID.

```ruby theme={null}
product = api_instance.product_controller_find_one('product-id')
puts "Product: #{product.name}"
```

**Parameters:**

* `id: String` - Product ID

**Returns:** `Product`

#### `product_controller_update(id, update_product_dto)`

Update a product.

```ruby theme={null}
update_dto = {
  price: 89.99,
  description: 'Updated description'
}

updated = api_instance.product_controller_update('product-id', update_dto)
puts "Product updated: #{updated.id}"
```

**Parameters:**

* `id: String` - Product ID
* `update_product_dto: Hash` - Fields to update

**Returns:** `Product`

#### `product_controller_remove(id)`

Delete a product.

```ruby theme={null}
api_instance.product_controller_remove('product-id')
puts 'Product deleted'
```

**Parameters:**

* `id: String` - Product ID

**Returns:** `nil`

#### `product_controller_upload_image(id, images)`

Upload images for a product.

```ruby theme={null}
images = [
  File.open('/path/to/image1.jpg'),
  File.open('/path/to/image2.jpg')
]

product = api_instance.product_controller_upload_image('product-id', images)
puts "Images uploaded for product: #{product.id}"
```

**Parameters:**

* `id: String` - Product ID
* `images: Array<File>` - Image files

**Returns:** `Product`

***

## Taxes

Configure and manage tax settings.

### Methods

#### `tax_controller_create(create_tax_dto)`

Create a new tax configuration.

```ruby theme={null}
require 'devdraft'

api_instance = Devdraft::TaxesApi.new

begin
  tax_dto = Devdraft::CreateTaxDto.new(
    name: 'Sales Tax',
    percentage: 8.5,
    country: 'US',
    state: 'CA'
  )
  
  tax = api_instance.tax_controller_create(tax_dto)
  puts "Tax created: #{tax.id}"
rescue Devdraft::ApiError => e
  puts "Error: #{e}"
end
```

**Parameters:**

* `create_tax_dto: CreateTaxDto` - Tax details

**Returns:** `Tax`

#### `tax_controller_find_all(opts = {})`

Get all tax configurations.

```ruby theme={null}
opts = { country: 'US' }

taxes = api_instance.tax_controller_find_all(opts)

taxes.each do |tax|
  puts "#{tax.name}: #{tax.percentage}%"
end
```

**Parameters:**

* `opts: Hash` - Optional parameters
  * `country: String` - Filter by country

**Returns:** `Array<Tax>`

#### `tax_controller_find_one(id)`

Get a tax configuration by ID.

```ruby theme={null}
tax = api_instance.tax_controller_find_one('tax-id')
puts "Tax: #{tax.name}"
```

**Parameters:**

* `id: String` - Tax ID

**Returns:** `Tax`

#### `tax_controller_update(id, update_tax_dto)`

Update a tax configuration.

```ruby theme={null}
update_dto = Devdraft::UpdateTaxDto.new(percentage: 9.0)
updated = api_instance.tax_controller_update('tax-id', update_dto)
puts "Tax updated: #{updated.id}"
```

**Parameters:**

* `id: String` - Tax ID
* `update_tax_dto: UpdateTaxDto` - Fields to update

**Returns:** `Tax`

#### `tax_controller_remove(id)`

Delete a tax configuration.

```ruby theme={null}
api_instance.tax_controller_remove('tax-id')
puts 'Tax deleted'
```

**Parameters:**

* `id: String` - Tax ID

**Returns:** `nil`

***

## Test Payments

Process test payments in sandbox environment.

### Methods

#### `test_payment_controller_create_payment_v0(payment_request_dto)`

Create a test payment.

```ruby theme={null}
require 'devdraft'

api_instance = Devdraft::TestPaymentsApi.new

begin
  payment_dto = Devdraft::PaymentRequestDto.new(
    amount: 100.00,
    currency: 'USD',
    customer_id: 'test-customer-id',
    idempotency_key: 'unique-key-123'
  )
  
  payment = api_instance.test_payment_controller_create_payment_v0(payment_dto)
  puts "Test payment: #{payment.id}"
  puts "Status: #{payment.status}"
rescue Devdraft::ApiError => e
  puts "Error: #{e}"
end
```

**Parameters:**

* `payment_request_dto: PaymentRequestDto` - Payment details

**Returns:** `PaymentResponseDto`

#### `test_payment_controller_get_payment_v0(id)`

Get test payment details by ID.

```ruby theme={null}
payment = api_instance.test_payment_controller_get_payment_v0('payment-id')
puts "Payment status: #{payment.status}"
```

**Parameters:**

* `id: String` - Payment ID

**Returns:** `PaymentResponseDto`

#### `test_payment_controller_refund_payment_v0(id, opts = {})`

Refund a test payment.

```ruby theme={null}
opts = { refund_amount: 50.00 }

refund = api_instance.test_payment_controller_refund_payment_v0('payment-id', opts)
puts "Refund processed: #{refund.id}"
```

**Parameters:**

* `id: String` - Payment ID
* `opts: Hash` - Optional parameters
  * `refund_amount: Float` - Amount to refund (defaults to full amount)

**Returns:** `RefundResponseDto`

***

## Transfers

Initiate and manage fund transfers between different payment rails.

### Methods

#### `transfer_controller_create_direct_bank_transfer(create_direct_bank_transfer_dto)`

Create a direct bank transfer.

```ruby theme={null}
require 'devdraft'

api_instance = Devdraft::TransfersApi.new

begin
  transfer_dto = Devdraft::CreateDirectBankTransferDto.new(
    wallet_id: 'wallet-id',
    payment_rail: 'wire',
    source_currency: 'usd',
    destination_currency: 'usdc',
    amount: 1000.00
  )
  
  transfer = api_instance.transfer_controller_create_direct_bank_transfer(transfer_dto)
  puts "Transfer created: #{transfer.id}"
  puts "Bank instructions: #{transfer.source_deposit_instructions}"
rescue Devdraft::ApiError => e
  puts "Error: #{e}"
end
```

**Parameters:**

* `create_direct_bank_transfer_dto: CreateDirectBankTransferDto` - Transfer details

**Returns:** `Transfer`

**See also:** [Direct Bank Transfer Guide](/docs/developers/transfers/direct-bank-transfer)

#### `transfer_controller_create_direct_wallet_transfer(create_direct_wallet_transfer_dto)`

Create a direct wallet transfer.

```ruby theme={null}
transfer_dto = Devdraft::CreateDirectWalletTransferDto.new(
  wallet_id: 'wallet-id',
  network: 'solana',
  stable_coin_currency: 'usdc',
  amount: 500.00
)

transfer = api_instance.transfer_controller_create_direct_wallet_transfer(transfer_dto)
puts "Transfer created: #{transfer.id}"
puts "Deposit address: #{transfer.source_deposit_instructions.to_address}"
```

**Parameters:**

* `create_direct_wallet_transfer_dto: CreateDirectWalletTransferDto` - Transfer details

**Returns:** `Transfer`

**See also:** [Direct Wallet Transfer Guide](/docs/developers/transfers/direct-wallet-transfer)

#### `transfer_controller_create_external_bank_transfer(create_external_bank_transfer_dto)`

Create an external bank transfer (from your wallet to external bank).

```ruby theme={null}
transfer_dto = Devdraft::CreateExternalBankTransferDto.new(
  source_wallet_id: 'wallet-id',
  destination_bank_account_id: 'bank-account-id',
  amount: 1000.00,
  currency: 'USD'
)

transfer = api_instance.transfer_controller_create_external_bank_transfer(transfer_dto)
puts "External bank transfer: #{transfer.id}"
```

**Parameters:**

* `create_external_bank_transfer_dto: CreateExternalBankTransferDto` - Transfer details

**Returns:** `Transfer`

#### `transfer_controller_create_external_stablecoin_transfer(create_external_stablecoin_transfer_dto)`

Create an external stablecoin transfer (from your wallet to external wallet).

```ruby theme={null}
transfer_dto = Devdraft::CreateExternalStablecoinTransferDto.new(
  source_wallet_id: 'wallet-id',
  destination_address: '0x742d35Cc6Ff82a8C2D8D1Da9da17c7eDfD5bE0a3',
  network: 'ethereum',
  currency: 'usdc',
  amount: 250.00
)

transfer = api_instance.transfer_controller_create_external_stablecoin_transfer(transfer_dto)
puts "External stablecoin transfer: #{transfer.id}"
```

**Parameters:**

* `create_external_stablecoin_transfer_dto: CreateExternalStablecoinTransferDto` - Transfer details

**Returns:** `Transfer`

#### `transfer_controller_create_stablecoin_conversion(create_stablecoin_conversion_dto)`

Convert between different stablecoins or networks.

```ruby theme={null}
conversion_dto = Devdraft::CreateStablecoinConversionDto.new(
  source_wallet_id: 'wallet-id',
  destination_wallet_id: 'wallet-id',
  source_network: 'ethereum',
  destination_network: 'solana',
  source_currency: 'usdc',
  destination_currency: 'usdc',
  amount: 1000.00
)

conversion = api_instance.transfer_controller_create_stablecoin_conversion(conversion_dto)
puts "Conversion ID: #{conversion.id}"
puts "Exchange rate: #{conversion.exchange_rate.rate}"
puts "Estimated completion: #{conversion.estimated_completion}"
```

**Parameters:**

* `create_stablecoin_conversion_dto: CreateStablecoinConversionDto` - Conversion details

**Returns:** `Conversion`

**See also:** [Stablecoin Conversion Guide](/docs/developers/transfers/stablecoin-conversion)

***

## Wallets

Manage wallets and query balances.

### Methods

#### `wallet_controller_get_wallets()`

Get all wallets for your application.

```ruby theme={null}
require 'devdraft'

api_instance = Devdraft::WalletsApi.new

begin
  api_instance.wallet_controller_get_wallets
  puts 'Wallets retrieved successfully'
rescue Devdraft::ApiError => e
  puts "Error: #{e}"
end
```

**Returns:** `nil`

<Info>
  The response contains wallet IDs that you can use for transfers and other operations. In a future SDK version, this will return typed wallet objects.
</Info>

***

## Webhooks

Configure webhooks to receive real-time event notifications.

### Methods

#### `webhook_controller_create(create_webhook_dto)`

Create a new webhook.

```ruby theme={null}
require 'devdraft'

api_instance = Devdraft::WebhooksApi.new

begin
  webhook_dto = Devdraft::CreateWebhookDto.new(
    url: 'https://your-app.com/webhooks/devdraft',
    name: 'Production Webhook',
    is_active: true,
    encrypted: false
  )
  
  webhook = api_instance.webhook_controller_create(webhook_dto)
  puts "Webhook ID: #{webhook.id}"
  puts "Signing secret: #{webhook.signing_secret}"
rescue Devdraft::ApiError => e
  puts "Error: #{e}"
end
```

**Parameters:**

* `create_webhook_dto: CreateWebhookDto` - Webhook configuration

**Returns:** `WebhookResponseDto`

**See also:** [Webhooks Overview](/docs/developers/webhooks/overview)

#### `webhook_controller_find_all(opts = {})`

Get all webhooks.

```ruby theme={null}
opts = {
  page: 1,
  limit: 20,
  active: true
}

webhooks = api_instance.webhook_controller_find_all(opts)

webhooks.each do |webhook|
  puts "#{webhook.name}: #{webhook.url}"
  puts "Active: #{webhook.is_active}"
end
```

**Parameters:**

* `opts: Hash` - Optional parameters
  * `page: Integer` - Page number
  * `limit: Integer` - Items per page
  * `active: Boolean` - Filter by active status

**Returns:** `Array<WebhookResponseDto>`

#### `webhook_controller_find_one(id)`

Get a webhook by ID.

```ruby theme={null}
webhook = api_instance.webhook_controller_find_one('webhook-id')

puts "Webhook: #{webhook.name}"
puts "URL: #{webhook.url}"
puts "Delivery stats: #{webhook.delivery_stats}"
```

**Parameters:**

* `id: String` - Webhook ID

**Returns:** `WebhookResponseDto`

#### `webhook_controller_update(id, update_webhook_dto)`

Update a webhook.

```ruby theme={null}
update_dto = Devdraft::UpdateWebhookDto.new(
  url: 'https://your-app.com/webhooks/new-endpoint',
  is_active: true
)

updated = api_instance.webhook_controller_update('webhook-id', update_dto)
puts "Webhook updated: #{updated.id}"
```

**Parameters:**

* `id: String` - Webhook ID
* `update_webhook_dto: UpdateWebhookDto` - Fields to update

**Returns:** `WebhookResponseDto`

#### `webhook_controller_remove(id)`

Delete a webhook.

```ruby theme={null}
api_instance.webhook_controller_remove('webhook-id')
puts 'Webhook deleted'
```

**Parameters:**

* `id: String` - Webhook ID

**Returns:** `nil`

***

## Error Handling

All SDK methods may raise `Devdraft::ApiError`. Handle them appropriately:

```ruby theme={null}
require 'devdraft'

begin
  transfer = transfers_api.transfer_controller_create_direct_wallet_transfer(transfer_dto)
  puts "Transfer created: #{transfer.id}"
rescue Devdraft::ApiError => e
  case e.code
  when 400
    puts "Invalid request: #{e.message}"
  when 401
    puts 'Authentication failed - check your API credentials'
  when 404
    puts "Resource not found: #{e.message}"
  when 422
    puts "Validation error: #{e.message}"
  when 429
    puts 'Rate limited - please retry later'
  else
    puts "API error (#{e.code}): #{e.message}"
  end
  
  # Access response body for more details
  puts "Response body: #{e.response_body}" if e.response_body
rescue StandardError => e
  puts "Unexpected error: #{e.message}"
end
```

## Best Practices

<Steps>
  <Step title="Use Configuration Block">
    Set up configuration once at the start of your application.

    ```ruby theme={null}
    # In config/initializers/devdraft.rb (Rails)
    # or at the top of your script

    Devdraft.configure do |config|
      config.api_key['x-client-key'] = ENV['DEVDRAFT_CLIENT_KEY']
      config.api_key['x-client-secret'] = ENV['DEVDRAFT_CLIENT_SECRET']
      config.base_url = ENV.fetch('DEVDRAFT_API_URL', 'https://api.devdraft.ai')
      
      # Optional: Configure debugging
      config.debugging = ENV['DEVDRAFT_DEBUG'] == 'true'
      
      # Optional: Configure timeout
      config.timeout = 30
    end
    ```
  </Step>

  <Step title="Use Environment Variables">
    Store credentials in environment variables, never in source code.

    ```ruby theme={null}
    # Use dotenv gem for development
    require 'dotenv/load'

    Devdraft.configure do |config|
      config.api_key['x-client-key'] = ENV.fetch('DEVDRAFT_CLIENT_KEY')
      config.api_key['x-client-secret'] = ENV.fetch('DEVDRAFT_CLIENT_SECRET')
    end
    ```
  </Step>

  <Step title="Proper Exception Handling">
    Always wrap API calls in begin/rescue blocks.

    ```ruby theme={null}
    def create_transfer(amount)
      transfer_dto = Devdraft::CreateDirectWalletTransferDto.new(
        wallet_id: 'wallet-id',
        network: 'solana',
        stable_coin_currency: 'usdc',
        amount: amount
      )
      
      begin
        transfers_api.transfer_controller_create_direct_wallet_transfer(transfer_dto)
      rescue Devdraft::ApiError => e
        Rails.logger.error("Transfer failed: #{e.message}")
        raise
      end
    end
    ```
  </Step>

  <Step title="Use Symbols for Hash Keys">
    Follow Ruby conventions by using symbols for hash keys.

    ```ruby theme={null}
    # Good: Using symbols
    opts = {
      page: 1,
      limit: 20,
      status: 'ACTIVE'
    }

    # Works but not idiomatic
    opts = {
      'page' => 1,
      'limit' => 20,
      'status' => 'ACTIVE'
    }
    ```
  </Step>

  <Step title="Use Blocks for Iteration">
    Use Ruby blocks for clean iteration over collections.

    ```ruby theme={null}
    # Good: Using blocks
    customers.each do |customer|
      puts "#{customer.first_name} #{customer.last_name}"
    end

    # Also good: Using map for transformations
    customer_names = customers.map { |c| "#{c.first_name} #{c.last_name}" }
    ```
  </Step>

  <Step title="Implement Logging">
    Use Ruby's built-in Logger or Rails logger.

    ```ruby theme={null}
    require 'logger'

    logger = Logger.new(STDOUT)
    logger.level = Logger::INFO

    begin
      logger.info("Creating transfer for amount: #{amount}")
      transfer = transfers_api.transfer_controller_create_direct_wallet_transfer(dto)
      logger.info("Transfer created: #{transfer.id}")
    rescue Devdraft::ApiError => e
      logger.error("Transfer failed: #{e.message}")
      raise
    end
    ```
  </Step>
</Steps>

## Testing with RSpec

Example RSpec test for SDK integration:

```ruby theme={null}
require 'spec_helper'
require 'devdraft'

RSpec.describe 'Devdraft Webhooks' do
  before(:all) do
    Devdraft.configure do |config|
      config.api_key['x-client-key'] = ENV['DEVDRAFT_TEST_CLIENT_KEY']
      config.api_key['x-client-secret'] = ENV['DEVDRAFT_TEST_CLIENT_SECRET']
    end
  end
  
  let(:api_instance) { Devdraft::WebhooksApi.new }
  
  describe '#webhook_controller_create' do
    it 'creates a webhook successfully' do
      webhook_dto = Devdraft::CreateWebhookDto.new(
        url: 'https://test.example.com/webhook',
        name: 'Test Webhook',
        is_active: true,
        encrypted: false
      )
      
      webhook = api_instance.webhook_controller_create(webhook_dto)
      
      expect(webhook.id).not_to be_nil
      expect(webhook.name).to eq('Test Webhook')
      expect(webhook.is_active).to be true
    end
    
    it 'raises ApiError with invalid URL' do
      webhook_dto = Devdraft::CreateWebhookDto.new(
        url: 'invalid-url',
        name: 'Invalid Webhook',
        is_active: true
      )
      
      expect {
        api_instance.webhook_controller_create(webhook_dto)
      }.to raise_error(Devdraft::ApiError)
    end
  end
  
  describe '#webhook_controller_find_all' do
    it 'returns an array of webhooks' do
      webhooks = api_instance.webhook_controller_find_all
      
      expect(webhooks).to be_an(Array)
      webhooks.each do |webhook|
        expect(webhook).to be_a(Devdraft::WebhookResponseDto)
      end
    end
  end
end
```

## Rails Integration

### Configuration

Create an initializer for Rails applications:

```ruby theme={null}
# config/initializers/devdraft.rb

Devdraft.configure do |config|
  config.api_key['x-client-key'] = Rails.application.credentials.devdraft[:client_key]
  config.api_key['x-client-secret'] = Rails.application.credentials.devdraft[:client_secret]
  config.base_url = ENV.fetch('DEVDRAFT_API_URL', 'https://api.devdraft.ai')
  config.debugging = Rails.env.development?
end
```

### Service Object Pattern

Create service objects for cleaner Rails integration:

```ruby theme={null}
# app/services/devdraft_service.rb

class DevdraftService
  def initialize
    @transfers_api = Devdraft::TransfersApi.new
    @webhooks_api = Devdraft::WebhooksApi.new
  end
  
  def create_transfer(wallet_id:, amount:)
    transfer_dto = Devdraft::CreateDirectWalletTransferDto.new(
      wallet_id: wallet_id,
      network: 'solana',
      stable_coin_currency: 'usdc',
      amount: amount
    )
    
    @transfers_api.transfer_controller_create_direct_wallet_transfer(transfer_dto)
  rescue Devdraft::ApiError => e
    Rails.logger.error("Devdraft transfer error: #{e.message}")
    raise
  end
  
  def create_webhook(url:, name:)
    webhook_dto = Devdraft::CreateWebhookDto.new(
      url: url,
      name: name,
      is_active: true,
      encrypted: false
    )
    
    @webhooks_api.webhook_controller_create(webhook_dto)
  rescue Devdraft::ApiError => e
    Rails.logger.error("Devdraft webhook error: #{e.message}")
    raise
  end
end
```

### Controller Example

Use the service in your Rails controllers:

```ruby theme={null}
# app/controllers/transfers_controller.rb

class TransfersController < ApplicationController
  def create
    service = DevdraftService.new
    
    transfer = service.create_transfer(
      wallet_id: params[:wallet_id],
      amount: params[:amount].to_f
    )
    
    render json: {
      success: true,
      transfer_id: transfer.id,
      deposit_address: transfer.source_deposit_instructions&.to_address
    }
  rescue Devdraft::ApiError => e
    render json: {
      success: false,
      error: e.message
    }, status: e.code
  rescue StandardError => e
    render json: {
      success: false,
      error: 'Internal server error'
    }, status: :internal_server_error
  end
end
```

### Background Jobs

Process API calls in background jobs:

```ruby theme={null}
# app/jobs/create_transfer_job.rb

class CreateTransferJob < ApplicationJob
  queue_as :default
  
  def perform(wallet_id, amount)
    service = DevdraftService.new
    transfer = service.create_transfer(wallet_id: wallet_id, amount: amount)
    
    # Notify user or update database
    Rails.logger.info("Transfer created: #{transfer.id}")
  rescue Devdraft::ApiError => e
    Rails.logger.error("Transfer job failed: #{e.message}")
    # Optionally retry or notify admin
    raise
  end
end
```

## Next Steps

<CardGroup cols={2}>
  <Card title="SDK Quickstart" href="/docs/developers/sdk-quickstart" icon="rocket">
    Complete integration guide with examples
  </Card>

  <Card title="Transfers" href="/docs/developers/transfers/direct-wallet-transfer" icon="arrow-right-arrow-left">
    Learn about initiating transfers
  </Card>

  <Card title="Webhooks" href="/docs/developers/webhooks/overview" icon="bell">
    Set up webhook notifications
  </Card>

  <Card title="API Reference" href="/docs/developers/api-reference" icon="book">
    Complete REST API documentation
  </Card>
</CardGroup>