Skip to main content
POST
/
v1
/
exchanges
Create a new Exchange transaction
curl --request POST \
  --url https://sandbox-api.borderless.xyz/v1/exchanges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": {
    "type": "fiat"
  },
  "to": {
    "type": "fiat"
  },
  "amount": "100.00",
  "accountId": "acc_123"
}
'
{
  "id": "<string>",
  "source": {
    "amount": "<string>",
    "fiatCurrency": "<string>",
    "accountId": "<string>",
    "accountName": "<string>",
    "sender": {
      "name": "<string>",
      "legalName": "<string>",
      "description": "<string>",
      "taxIdLast4": "<string>",
      "bankName": "<string>",
      "bankRoutingNumberLast4": "<string>",
      "bankAccountNumberLast4": "<string>",
      "accountNumberLast4": "<string>",
      "traceNumber": "<string>",
      "originatorName": "<string>",
      "beneficiaryName": "<string>",
      "wireMessage": "<string>",
      "imad": "<string>",
      "iban": "<string>",
      "ibanLast4": "<string>",
      "bic": "<string>",
      "sortCode": "<string>",
      "clabe": "<string>",
      "trackingNumber": "<string>",
      "reference": "<string>",
      "uetr": "<string>",
      "paymentScheme": "<string>",
      "recipientName": "<string>"
    }
  },
  "destination": {
    "amount": "<string>",
    "fiatCurrency": "<string>",
    "imad": "<string>",
    "reference": "<string>",
    "omad": "<string>",
    "traceNumber": "<string>",
    "externalAddress": "<string>",
    "accountId": "<string>",
    "accountName": "<string>",
    "paymentInstructionId": "<string>"
  },
  "instructions": {},
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "txHash": [
    "<string>"
  ],
  "feeAmount": {},
  "failureReason": {
    "details": [
      {
        "path": "paymentInstruction",
        "pfiErrorMessage": "bank.transitNumber must match /^([0-9]{3}-[0-9]{5}|[0-9]{5}-[0-9]{3})$/ regular expression"
      }
    ],
    "message": "Validation error from PFI"
  },
  "depositInstruction": {
    "details": {
      "depositMessage": "<string>",
      "bankAccountNumber": "<string>",
      "bankRoutingNumber": "<string>",
      "bankBeneficiaryName": "<string>",
      "bankBeneficiaryAddress": "<string>",
      "bankName": "<string>",
      "bankAddress": "<string>",
      "bic": "<string>"
    }
  },
  "destinationPaymentInstruction": {
    "id": "<string>",
    "name": "<string>",
    "currency": "USD",
    "country": "US",
    "deleted": false,
    "createdAt": "2023-11-07T05:31:56Z",
    "details": {
      "bankName": "Chase",
      "accountHolderName": "John Doe",
      "bankAccountNumberLast4": "6789",
      "bankRoutingNumber": "021000021",
      "address": {
        "id": "<string>",
        "street1": "<string>",
        "street2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postalCode": "<string>"
      },
      "bankSlug": "<string>",
      "bankCode": "<string>",
      "phone": "<string>",
      "taxId": "<string>",
      "bankAccountNumber": "123456789"
    }
  },
  "withdrawalOnchainInstruction": {
    "id": "<string>",
    "amount": "100.00",
    "asset": "BTC",
    "fromAddress": "<string>",
    "toAddress": "<string>",
    "spenderAddress": "<string>",
    "onchainInstructionTransaction": {
      "id": "<string>",
      "to": "<string>",
      "from": "<string>",
      "data": "<string>",
      "nonce": "<string>",
      "value": "<string>",
      "chainId": 123,
      "gasLimit": "<string>",
      "gasPrice": "<string>",
      "fee": "<string>",
      "unsignedTx": "<string>",
      "psbt": "<string>",
      "inputs": {},
      "outputs": {},
      "walletId": "<string>",
      "body": {},
      "visible": true,
      "txID": "<string>",
      "rawData": {},
      "rawDataHex": "<string>",
      "spender": "<string>",
      "mint": "<string>"
    }
  },
  "counterPartyIdentityId": "<string>",
  "virtualAccountId": "<string>",
  "staleSince": "2023-11-07T05:31:56Z",
  "developerFeeAmount": {},
  "refundResolution": {
    "supported": true,
    "requiresManualAction": true,
    "destination": {},
    "reason": {},
    "completedAt": "2023-11-07T05:31:56Z",
    "failedAt": "2023-11-07T05:31:56Z"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
from
object
required

Asset leg to convert from.

​
to
object
required

Asset leg to convert to.

​
amount
string
required

Amount to convert from the source leg.

Example:

"100.00"

​
accountId
string
required

Identifier of the PFI account where the conversion takes place.

Example:

"acc_123"

Response

Successfully created Exchange transaction data.

​
id
string
required
​
type
enum<string>
required
Available options:
Deposit,
Withdrawal,
Exchange
​
status
enum<string>
required
Available options:
Submitted,
Verifying,
Orchestrating,
Pending,
Processing,
Completed,
Failed,
Cancelled,
Refunded
​
pfiName
enum<string>
required
Available options:
Bridge,
Koywe,
Kotanipay,
Hercle,
Bitso,
Yellowcard,
TraceFinance,
HoneyCoin,
BlindPay,
Finity,
Infinia,
Walapay,
Abra,
Yativo,
Capa,
Bivo,
Cobre,
Avenia,
Brale,
BVNK,
CoinsPH,
Iron,
Enigma,
Juicyway,
Kira,
TripleA,
Onmeta,
Alfred
​
country
enum<string>
required
Available options:
AF,
AL,
DZ,
AS,
AD,
AO,
AI,
AQ,
AG,
AR,
AM,
AW,
AU,
AT,
AZ,
BS,
BH,
BD,
BB,
BY,
BE,
BZ,
BJ,
BM,
BT,
BO,
BQ,
BA,
BW,
BV,
BR,
IO,
BN,
BG,
BF,
BI,
CV,
KH,
CM,
CA,
KY,
CF,
TD,
CL,
CN,
CX,
CC,
CO,
KM,
CD,
CG,
CK,
CR,
HR,
CU,
CW,
CY,
CZ,
CI,
DK,
DJ,
DM,
DO,
EC,
EG,
SV,
GQ,
ER,
EE,
SZ,
ET,
FK,
FO,
FJ,
FI,
FR,
GF,
PF,
TF,
GA,
GM,
GE,
DE,
GH,
GI,
GR,
GL,
GD,
GP,
GU,
GT,
GG,
GN,
GW,
GY,
HT,
HM,
VA,
HN,
HK,
HU,
IS,
IN,
ID,
IR,
IQ,
IE,
IM,
IL,
IT,
JM,
JP,
JE,
JO,
KZ,
KE,
KI,
KP,
KR,
KW,
KG,
LA,
LV,
LB,
LS,
LR,
LY,
LI,
LT,
LU,
MO,
MG,
MW,
MY,
MV,
ML,
MT,
MH,
MQ,
MR,
MU,
YT,
MX,
FM,
MD,
MC,
MN,
ME,
MS,
MA,
MZ,
MM,
NA,
NR,
NP,
NL,
NC,
NZ,
NI,
NE,
NG,
NU,
NF,
MP,
NO,
OM,
PK,
PW,
PS,
PA,
PG,
PY,
PE,
PH,
PN,
PL,
PT,
PR,
QA,
MK,
RO,
RU,
RW,
RE,
BL,
SH,
KN,
LC,
MF,
PM,
VC,
WS,
SM,
ST,
SA,
SN,
RS,
SC,
SL,
SG,
SX,
SK,
SI,
SB,
SO,
ZA,
GS,
SS,
ES,
LK,
SD,
SR,
SJ,
SE,
CH,
SY,
TW,
TJ,
TZ,
TH,
TL,
TG,
TK,
TO,
TT,
TN,
TR,
TM,
TC,
TV,
UG,
UA,
AE,
GB,
UM,
US,
UY,
UZ,
VU,
VE,
VN,
VG,
VI,
WF,
EH,
YE,
ZM,
ZW,
AX
​
source
object
required
​
destination
object
required
​
instructions
object
required
deprecated

Deprecated. Use withdrawalOnchainInstruction or depositInstruction instead.

​
createdAt
string<date-time>
required
​
updatedAt
string<date-time>
required
​
txHash
string[]
required
​
feeAmount
object
required
​
failureReason
object
required
Example:
{
  "details": [
    {
      "path": "paymentInstruction",
      "pfiErrorMessage": "bank.transitNumber must match /^([0-9]{3}-[0-9]{5}|[0-9]{5}-[0-9]{3})$/ regular expression"
    }
  ],
  "message": "Validation error from PFI"
}
​
depositInstruction
object
required
​
destinationPaymentInstruction
object
required
​
withdrawalOnchainInstruction
object
required
​
counterPartyIdentityId
string | null
required
​
virtualAccountId
string | null
required
​
reconciliationStatus
enum<string>
required
Available options:
Matched,
Mismatched,
Missing,
PfiError
​
rateGrade
enum<string>
required
Available options:
Competitive,
InLine,
OffMarket
​
rateStatus
enum<string>
required
Available options:
Classified,
Calibrating,
Stale,
NoRateProduced,
Syncing
​
rateConfidenceTier
enum<string>
required
Available options:
Strong,
Standard
​
lastKnownGrade
enum<string>
required
Available options:
Competitive,
InLine,
OffMarket
​
staleSince
string<date-time> | null
required
​
developerFeeAmount
object
required
​
refundResolution
object