Skip to main content
POST
/
autoramp
Create autoramp (pay by reference)
curl --request POST \
  --url https://api.sandbox.iron.xyz/autoramp \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'IDEMPOTENCY-KEY: <idempotency-key>' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "destination_wallet_address": "<string>",
  "token": "<string>",
  "network": "Ethereum",
  "pay_by_reference": false,
  "name": "<string>",
  "external_id": "<string>"
}
'
{
  "autoramp_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "payment_reference": "<string>",
  "destination_mapping": {
    "wallet_address": "<string>",
    "token": "<string>",
    "network": "<string>"
  }
}

Authorizations

​
X-API-Key
string
header
required

Partner API key from the Developer → API Keys section of the Partner Dashboard.

Headers

​
IDEMPOTENCY-KEY
string<uuid>
required

UUID ensuring this create operation is only processed once.

​
X-SUB-PARTNER-ID
string<uuid>

Optional sub-partner UUID; if set, the autoramp is created for that sub-partner.

Body

application/json; charset=utf-8
​
customer_id
string<uuid>
required

Customer this autoramp belongs to.

​
destination_wallet_address
string
required

Destination wallet address that will receive funds; bound to the generated payment reference when pay_by_reference is true.

​
token
string
required

Destination token identifier (e.g. USDC).

​
network
string
required

Blockchain / network for the destination wallet (e.g. Ethereum, Solana, Base).

Example:

"Ethereum"

​
pay_by_reference
boolean
default:false

Optional. If omitted, treated as false (same as sending false) so existing partner integrations that do not send this field remain valid. If true, enables pay-by-reference: Iron generates a payment reference in the response and maps it to the destination wallet, token, and network. If false or omitted, behaviour matches a standard autoramp create (preview — details may align with POST /autoramps in the main spec).

​
name
string

Optional display name for the autoramp.

​
external_id
string

Optional partner-supplied external id for correlation.

Response

Autoramp created; when pay-by-reference is enabled, includes the payment reference and destination mapping.

​
autoramp_id
string<uuid>
required

Identifier of the created autoramp.

​
payment_reference
string

Stable reference to include on each payment when using this ramp with pay-by-reference. Included when pay_by_reference was true in the request (or resolved to true); omitted when the field was omitted or false.

​
destination_mapping
object

Confirms the wallet, token, and network stored for this payment reference when pay-by-reference is enabled.