Quotes

Lock an exchange rate before creating an Autoramp.

Request a guaranteed exchange rate for a currency conversion. The quote locks pricing for a defined period so your users see predictable amounts.

How It Works

A quote binds a conversion rate between two currencies for a limited window. Create a quote with GET /autoramps/quote, then pass the signed result to POST /autoramps to create an Autoramp that executes at the locked rate.

Without a quote, conversions execute at the current mid-market rate. With a quote, the rate is fixed for the lock duration you specify.

Key Parameters

Rate lock duration: time window where the quoted rate and fee are fully guaranteed. Funds received in this window execute at the quoted price.

Validity period: total time the Autoramp remains active. Funds received after this period are refunded.

Expiry Policies

What happens when funds arrive after the rate lock expires depends on the rate_expiry_policy you set.

Return

Validity period equals rate lock duration. Funds arriving after the lock expires are refunded.

Example:

• Quote: 100 USD for 0.0025 BTC
• Rate lock: 10 minutes, validity: 10 minutes
• Funds arrive at 12 minutes
• Result: refunded (both windows expired)

Slippage

Validity period extends beyond the rate lock. Funds arriving after the lock execute if the market rate is within slippage_tolerance_in_bips. Otherwise they are refunded or requoted.

Example (within tolerance):

• Quote: 100 USD for 0.0025 BTC, 5 bips slippage
• Rate lock: 10 minutes, validity: 1 hour
• Funds arrive at 20 minutes, market rate within 5 bips
• Result: executes at market rate

Example (outside tolerance):

• Same setup, but market rate exceeds 5 bips from quote
• Result: refunded or requoted

Prerequisites

Complete these before requesting a quote:

1. Create and verify a customer

   Register a customer via POST /customers and complete identity verification. The customer must reach Active status before they can transact.

   See Onboarding Lifecycle for the full flow.

2. Register a recipient address

   The recipient_account_id in your quote request must reference a registered and verified address.

   • Fiat offramps: register a bank account (SEPA, ACH, Wire, or SWIFT) via POST /addresses/fiat. The address must be verified before use. See Fiat Addresses.
   • Crypto swaps: register the destination wallet via POST /addresses/crypto. Self-hosted wallets require a signed proof-of-ownership message; hosted wallets require the custodian’s DID. See Crypto Addresses.
3. Authenticate your requests

   Include your API key in the X-API-Key header on every request. See Authentication.

Quote requests fail if the recipient_account_id references an address that has not been registered or has not passed verification.

Implementation

1. Create a quote

   GET /autoramps/quote

   Request a signed quote that defines the conversion rate, lock duration, validity period, and fees. The quote must be passed unchanged when creating an Autoramp.

   API Example

   curl -X GET "https://api.sandbox.iron.xyz/api/autoramps/quote?customer_id=<your-customer-id>&source_currency_code=USDC&source_currency_chain=Ethereum&destination_currency_code=EUR&recipient_account_id=<your-fiat-address-id>&amount_out=100&rate_lock_duration_minutes=10&rate_expiry_policy=Return&expiry_in_hours=1&is_third_party=false" \
     -H "Accept: application/json; charset=utf-8" \
     -H "X-API-Key: <your-api-key>"
   

   Example response:

   {
     "amount_in": {
       "amount": "111.19863",
       "currency": { "blockchain": "Ethereum", "token": "USDC", "type": "Crypto" }
     },
     "amount_out": {
       "amount": "100",
       "currency": { "code": "EUR", "type": "Fiat" }
     },
     "customer_id": "<your-customer-id>",
     "deposit_account_type": "Iban",
     "destination_currency": { "code": "EUR", "type": "Fiat" },
     "fee": {
       "banking_fee": { "amount": "0.326434", "currency": { "blockchain": "Ethereum", "token": "USDC", "type": "Crypto" } },
       "iron_fee": { "amount": "0.326434", "currency": { "blockchain": "Ethereum", "token": "USDC", "type": "Crypto" } },
       "network_fee": { "amount": "1.734570", "currency": { "blockchain": "Ethereum", "token": "USDC", "type": "Crypto" } },
       "partner_fee": { "amount": "0", "currency": { "blockchain": "Ethereum", "token": "USDC", "type": "Crypto" } },
       "total_fee": { "amount": "2.387438", "currency": { "blockchain": "Ethereum", "token": "USDC", "type": "Crypto" } }
     },
     "fee_settlement": "deductedImmediately",
     "is_third_party": false,
     "quote_id": "e8cd73a4-54cc-4a34-916d-238c5ce5f898",
     "rate": "0.919023105",
     "rate_expiry_policy": "Return",
     "rate_lock_valid_until": "2025-03-14T11:37:24.250798+00:00",
     "recipient_account": {
       "type": "Fiat",
       "account_identifier": { "type": "SEPA", "iban": "DE89370400440532013000" }
     },
     "signature": "36665918454471c078724046bcb82698eac2fb6f5f91c58a0f1a3923c5d95a28",
     "slippage_tolerance_in_bips": null,
     "source_currency": { "blockchain": "Ethereum", "token": "USDC", "type": "Crypto" },
     "valid_until": "2025-03-14T11:37:24.250798+00:00"
   }
   
2. Create an Autoramp with the quote

   POST /autoramps

   Submit the signed quote payload to create an Autoramp. The Autoramp processes deposits at the locked rate until the quote expires.

   API Example

   curl -X POST "https://api.sandbox.iron.xyz/api/autoramps" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "IDEMPOTENCY-KEY: <your-idempotency-key>" \
     -H "X-API-Key: <your-api-key>" \
     -d '<signed-quote-payload-from-step-1>'
   

   Example response:

   {
     "id": "f8f9a8c7-d8b1-4f1a-8f15-7e6c8a1a8e50",
     "status": "Created",
     "deposit_account": {
       "type": "Crypto",
       "chain": "Ethereum",
       "address": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
     },
     "created_at": "2025-01-20T12:34:56Z",
     "source": "Quote",
     "quote": { ... }
   }
   

   The quote field contains the full signed quote object from Step 1.

The quote is digitally signed. Pass it verbatim into the POST /autoramps call. Any modification (changing values, omitting fields) causes the request to fail.

Query Parameters

Parameter	Type	Required	Description
customer_id	string (UUID)	Yes	Unique identifier for the customer.
source_currency_code	string	Yes	Currency or token being sent (e.g. USDC, USD).
source_currency_chain	string	Yes	Blockchain for the source currency (e.g. Ethereum, Polygon).
destination_currency_code	string	Yes	Currency or token being received (e.g. EUR, GBP).
destination_currency_chain	string	Conditional	Blockchain for the destination currency. Required for crypto-to-crypto quotes.
recipient_account_id	string (UUID)	Yes	UUID of a registered recipient account (fiat_address or verified_crypto_address).
recipient_account	string	No	Deprecated. Use recipient_account_id instead. Ignored when recipient_account_id is provided.
amount_out	string	Conditional	Desired output amount in the destination currency. Set either amount_out or amount_in, not both.
amount_in	string	Conditional	Desired input amount in the source currency. Set either amount_in or amount_out, not both.
rate_lock_duration_minutes	integer	Yes	Duration (in minutes) the rate is locked. Max: 20.
rate_expiry_policy	string	Yes	What happens when the rate lock expires. One of Return, Slippage.
slippage_tolerance_in_bips	string	Conditional	Allowable deviation from quoted rate (1 bip = 0.01%). Required when rate_expiry_policy is Slippage.
is_third_party	boolean	Yes	Whether this is a third-party payment Autoramp. Set to false for standard customer-owned accounts.
expiry_in_hours	integer	Yes	Duration (in hours) the quote is valid. Max: 24.

Autoramp Body Parameters

Parameter	Type	Required	Description
rate_expiry_policy	string	Yes	What happens when the rate expires. One of Return, Slippage.
slippage_tolerance_in_bips	string	Conditional	Allowable deviation from quoted rate (1 bip = 0.01%). Required when rate_expiry_policy is Slippage.
type	string	Yes	Either exact_in (fixed input) or exact_out (fixed output).
valid_until	string (ISO 8601)	Yes	Timestamp when the quote expires. Max 24 hours from creation.
rate_lock_valid_until	string (ISO 8601)	Yes	Timestamp until which the locked rate is guaranteed. Max 20 minutes from creation for stablecoin pairs.

The quote_id and signature pair authenticate the quote. If deposits don’t match the quoted amount_in, they are refunded. Once valid_until passes, the Autoramp expires automatically.

• Check valid_until before submitting. Expired quotes return 400 Bad Request.
• Use idempotency keys for POST /autoramps calls.
• Sandbox rates are simulated but signatures work identically to Production.

Error Handling

Status	Cause
400 Bad Request	Quote expired (valid_until passed) or signed payload was modified
401 Unauthorized	Missing or invalid API key
404 Not Found	recipient_account_id does not reference a registered address
422 Unprocessable Entity	Required parameter missing or invalid value

Autoramp

Create and manage Autoramps.

Autoramp Status

Interpret Autoramp statuses.