Create Transfer

post

Creates a cross-chain transfer session.

Best Effort Mode (executionMode: best_effort):

• Deposit any amount of the origin token to the returned depositAddress

• The recipient will receive the destination token, optimized for cost and speed

• Amount is optional and used for estimation only

• Fees are always deducted from the output

Exact Out Mode (executionMode: exact_out):

• Deposit exactly the originAmount to the returned depositAddress

• The recipient will receive the exact destinationAmount specified

• Amount is required and guaranteed

• Fee payer is configurable (sender/receiver)

Set dryMode: true to preview the transfer without creating an active session.

Body

application/json

originTokenstringRequired

The origin token in chain:address format

Example: base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

destinationTokenstringRequired

The destination token in chain:address format

Example: solana:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

recipientstringRequired

The recipient address in chain:address format

Example: solana:7aLBCrbn4jDNSxLLJYRRnKbkqA5cuaeaAzn74xS7eKPD

executionModestring · enumRequired

The execution mode for this transfer

Example: best_effortPossible values:

dryModebooleanOptional

If true, the deposit address will not be observed for deposits

Default: false

amountstringOptional

For best_effort: Optional, expected input amount in smallest units, used for estimation only For exact_out: Required, guaranteed output amount in smallest units that the recipient will receive

Example: 1000000

depositAddressSaltstringOptional

Optional suffix appended to recipient's address for deposit address generation. Use to create multiple deposit addresses for same recipient.

Example: order-123

appFeeUsdstringOptional

Optional fixed fee in USD for your application

Example: 1.25

appFeeBpsintegerOptional

Optional fee in basis points (100 bps = 1%) for your application

Example: 100

appFeePayerstring · enumOptional

Who pays the fee (only applicable for exact_out mode when appFeeUsd or appFeeBps is specified)

Default: receiverPossible values:

Responses

200

Transfer created successfully

application/json

idstringRequired

Unique transfer identifier

Example: txfr_1a2b3c4d5e6f

createdAtstring · date-timeRequired

Timestamp when the transfer was created

Example: 2024-01-15T10:30:00Z

updatedAtstring · date-timeRequired

Timestamp when the transfer was last updated

Example: 2024-01-15T10:32:00Z

statusstring · enumRequired

Current status of the transfer session

Example: waiting_for_depositPossible values:

originTokenstringOptional

The origin token in chain:address format

Example: base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

originAmountstringOptional

The expected origin amount in smallest units

Example: 1050000

destinationTokenstringOptional

The destination token in chain:address format

Example: solana:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

destinationAmountstringOptional

The target destination amount in smallest units. Estimated for best-effort, guaranteed for exact-out.

Example: 1000000

recipientstringOptional

The recipient address in chain:address format

Example: solana:7aLBCrbn4jDNSxLLJYRRnKbkqA5cuaeaAzn74xS7eKPD

depositAddressstringOptional

The deposit address in chain:address format

Example: base:0x4D9A6F3c7B2E1a8D5C0F9e7B6A4d2E8c1F3a5B7D

depositAcceptedTokenstringOptional

The deposited token in chain:address format. Populated when deposit is detected.

Example: base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

depositAcceptedAmountstringOptional

The amount accepted for processing in smallest units. Populated when deposit is detected.

Example: 1050000

depositAcceptedAtstring · date-timeOptional

Timestamp when the deposit was accepted. Populated when deposit is detected.

Example: 2024-01-15T10:31:00Z

depositSenderstringOptional

The address that sent the deposit in chain:address format. Populated when deposit is detected.

Example: base:0x1234567890abcdef1234567890abcdef12345678

depositTxHashstringOptional

The transaction hash of the deposit in chain:hash format. Populated when deposit is detected.

Example: base:0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

fillAmountstringOptional

The actual delivered amount in smallest units. Populated when transfer completes.

Example: 998000

fillAtstring · date-timeOptional

Timestamp when the fill was executed. Populated when transfer completes.

Example: 2024-01-15T10:33:00Z

fillTxHashstringOptional

The transaction hash of the fill in chain:hash format. Populated when transfer completes.

Example: solana:abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

executionModestring · enumOptional

The execution mode for this transfer

Example: best_effortPossible values:

etaSecondsintegerOptional

Estimated time to completion in seconds

Example: 120

feeUsdstringOptional

Total fee in USD

Example: 1.75

feeBpsstringOptional

Fee in basis points (100 bps = 1%)

Example: 25

post

/transfers

HTTPcURLJavaScriptPython

POST /transfers HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 362

{
  "originToken": "base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "destinationToken": "solana:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "recipient": "solana:7aLBCrbn4jDNSxLLJYRRnKbkqA5cuaeaAzn74xS7eKPD",
  "executionMode": "best_effort",
  "dryMode": false,
  "amount": "1000000",
  "depositAddressSalt": "order-123",
  "appFeeUsd": "1.25",
  "appFeeBps": 100,
  "appFeePayer": "receiver"
}

200

Transfer created successfully

{
  "id": "txfr_1a2b3c4d5e6f",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:32:00Z",
  "status": "waiting_for_deposit",
  "originToken": "base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "originAmount": "1050000",
  "destinationToken": "solana:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "destinationAmount": "1000000",
  "recipient": "solana:7aLBCrbn4jDNSxLLJYRRnKbkqA5cuaeaAzn74xS7eKPD",
  "depositAddress": "base:0x4D9A6F3c7B2E1a8D5C0F9e7B6A4d2E8c1F3a5B7D",
  "depositAcceptedToken": "base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "depositAcceptedAmount": "1050000",
  "depositAcceptedAt": "2024-01-15T10:31:00Z",
  "depositSender": "base:0x1234567890abcdef1234567890abcdef12345678",
  "depositTxHash": "base:0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "fillAmount": "998000",
  "fillAt": "2024-01-15T10:33:00Z",
  "fillTxHash": "solana:abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
  "executionMode": "best_effort",
  "etaSeconds": 120,
  "feeUsd": "1.75",
  "feeBps": "25"
}