Getting Started

This guide takes you from an API key to a transfer request. The route below is illustrative; choose a route returned by GET /v1/rails in your environment.

1. Create an API key

Create an API key in the Heron Dashboard:

1. Log in to the Heron Dashboard.
2. Open Developers > API Keys.
3. Select Create New Key.
4. Copy the secret into your secret manager. Heron displays it only once.

All examples use these shell variables:

export HERON_API_KEY="YOUR_API_KEY"
export HERON_API_URL="https://api.tryheron.com"

2. Confirm your connection

List the rails that have active provider support for your tenant in the current environment:

curl "$HERON_API_URL/v1/rails?activeOnly=true" \
  --header "X-API-Key: $HERON_API_KEY"

Each fiat rail identifies its country, currency, and payment method. Each crypto rail identifies its blockchain and asset. activeOnly=true excludes catalog routes whose activeProviderCount is zero. Provider availability can differ between sandbox and production.

3. Prepare the customer and destination

Before requesting a transfer-ready quote:

• onboard the individual or business represented by YOUR_ENTITY_ID
• create the destination fiat account or crypto wallet
• keep the returned destination id

See Identity Onboarding and the fiat-account or crypto-wallet sections of the API Reference for the required fields.

4. Request quotes

Request execution options with POST /v1/quotes.

The following example requests options for sending 1,000.00 USD from a US ACH rail to a Mexican SPEI rail. Replace the route with one returned by GET /v1/rails:

curl "$HERON_API_URL/v1/quotes" \
  --request POST \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $HERON_API_KEY" \
  --data '{
    "entityId": "YOUR_ENTITY_ID",
    "from": {
      "type": "FIAT",
      "country": "US",
      "currency": "USD",
      "method": "ACH"
    },
    "to": {
      "type": "FIAT",
      "country": "MX",
      "currency": "MXN",
      "method": "SPEI"
    },
    "amount": "1000.00",
    "fixedSide": "FROM",
    "destinationFiatAccountId": "YOUR_FIAT_ACCOUNT_ID",
    "activeOnly": true
  }'

The response contains options and advisories. Compare each option's amounts, fees, ETA, and expiry, then keep the selected option's id. See Quotes for selection and expiry rules.

5. Create the transfer

Create the transfer with POST /v1/transfers.

Bind the selected quote option to the saved destination. Idempotency-Key is required; generate a new stable value for each logical transfer and reuse it only when retrying the same request.

curl "$HERON_API_URL/v1/transfers" \
  --request POST \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $HERON_API_KEY" \
  --header "Idempotency-Key: transfer-order-1042" \
  --data '{
    "quoteOptionId": "YOUR_QUOTE_OPTION_ID",
    "destination": {
      "type": "FIAT_ACCOUNT",
      "fiatAccountId": "YOUR_FIAT_ACCOUNT_ID"
    },
    "entityId": "YOUR_ENTITY_ID",
    "clientReference": "order-1042"
  }'

Heron returns the created transfer. If the transfer needs funding, use the funding instructions on the transfer or create a funding session as described in Transfers.

6. Track completion

Retrieve the latest transfer state when you need an on-demand read:

curl "$HERON_API_URL/v1/transfers/YOUR_TRANSFER_ID" \
  --header "X-API-Key: $HERON_API_KEY"

For production workflows, subscribe to transfer.status_changed and transfer.leg_status_changed events instead of relying on frequent polling. See Customer Webhooks.

Next steps

• Use Sandbox Scenarios to exercise success, review, return, and failure states without moving funds.
• Add Customer Webhooks before replacing sandbox credentials with production credentials.
• Use Exports & Reporting for reconciliation workflows.