Bridge Transfers API
The Transfers API from Bridge — 5 operation(s) for transfers.
OpenAPI Specification
openapi: 3.0.2
info:
title: Bridge API Keys Transfers API
description: APIs to move into, out of, and between any form of a dollar
version: '1'
servers:
- url: https://api.bridge.xyz/v0
description: The base path for all resources
security:
- ApiKey: []
tags:
- name: Transfers
paths:
/transfers:
get:
summary: Get all transfers
tags:
- Transfers
parameters:
- $ref: '#/components/parameters/LimitParameter'
- $ref: '#/components/parameters/TransferStartingAfterParameter'
- $ref: '#/components/parameters/TransferEndingBeforeParameter'
- $ref: '#/components/parameters/TxHashParameter'
- $ref: '#/components/parameters/UpdatedAfterMsParameter'
- $ref: '#/components/parameters/UpdatedBeforeMsParameter'
- $ref: '#/components/parameters/TemplateIDParameter'
- $ref: '#/components/parameters/TransferStateParameter'
responses:
'200':
description: List of transfers (the returned list is empty if none found)
content:
application/json:
schema:
title: Transfers
type: object
required:
- count
- data
properties:
count:
type: integer
description: The number of transfers returned
data:
type: array
minItems: 0
items:
$ref: '#/components/schemas/TransferResponse'
examples:
TransfersFound:
summary: A non-empty list of transfers
value:
count: 2
data:
- $ref: '#/components/examples/AchOnrampFundsReceivedTransferResponse'
- $ref: '#/components/examples/AchOfframpTransferResponse'
NoTransfersFound:
summary: An empty list of transfers
value:
count: 0
data: []
'401':
$ref: '#/components/responses/AuthenticationError'
'500':
$ref: '#/components/responses/UnexpectedError'
post:
summary: Create a transfer
description: 'Create a transfer.
If this transfer cannot be created because the funding source is temporarily busy processing another update, this endpoint may return `409 resource_state_conflict`.
This is a transient, retryable response. You may safely retry the same request with the same `Idempotency-Key`.
'
tags:
- Transfers
parameters:
- $ref: '#/components/parameters/IdempotencyKeyParameter'
requestBody:
description: Transfer object to be created
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransferRequest'
responses:
'201':
description: Transfer object created
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/TransferResponse'
- $ref: '#/components/schemas/TransferRouteResponse'
examples:
AchOnrampTransferResponse:
$ref: '#/components/examples/AchOnrampTransferResponse'
AchOfframpTransferResponse:
$ref: '#/components/examples/AchOfframpTransferResponse'
AchOfframpWithMemoTransferResponse:
$ref: '#/components/examples/AchOfframpWithMemoTransferResponse'
WireOnrampTransferResponse:
$ref: '#/components/examples/WireOnrampTransferResponse'
WireOfframpTransferResponse:
$ref: '#/components/examples/WireOfframpTransferResponse'
SepaOnrampTransferResponse:
$ref: '#/components/examples/SepaOnrampTransferResponse'
SepaOfframpTransferResponse:
$ref: '#/components/examples/SepaOfframpTransferResponse'
PixOnrampTransferResponse:
$ref: '#/components/examples/PixOnrampTransferResponse'
PixOfframpTransferResponse:
$ref: '#/components/examples/PixOfframpTransferResponse'
SpeiOnrampTransferResponse:
$ref: '#/components/examples/SpeiOnrampTransferResponse'
SpeiOfframpTransferResponse:
$ref: '#/components/examples/SpeiOfframpTransferResponse'
BreBOnrampTransferResponse:
$ref: '#/components/examples/BreBOnrampTransferResponse'
BreBOfframpTransferResponse:
$ref: '#/components/examples/BreBOfframpTransferResponse'
CoBankTransferOnrampTransferResponse:
$ref: '#/components/examples/CoBankTransferOnrampTransferResponse'
CoBankTransferOfframpTransferResponse:
$ref: '#/components/examples/CoBankTransferOfframpTransferResponse'
ValidTransferRouteResponse:
$ref: '#/components/examples/ValidTransferRouteResponse'
'401':
$ref: '#/components/responses/AuthenticationError'
'400':
$ref: '#/components/responses/BadRequestError'
'409':
$ref: '#/components/responses/ResourceStateConflictError'
'403':
$ref: '#/components/responses/TransferAmlError'
'500':
$ref: '#/components/responses/UnexpectedError'
/transfers/pending:
get:
summary: List transfers with pending USDT trades
description: 'Returns transfers that have a stuck USDT-to-USD trade awaiting execution. Results are sorted by creation time (newest first) and paginated.
Use `POST /transfers/{transferID}/execute` to force-execute a pending trade at the current market rate.
'
tags:
- Transfers
parameters:
- $ref: '#/components/parameters/LimitParameter'
- $ref: '#/components/parameters/TransferStartingAfterParameter'
- $ref: '#/components/parameters/TransferEndingBeforeParameter'
responses:
'200':
description: List of transfers with pending trades (the returned list is empty if none found)
content:
application/json:
schema:
title: PendingTransfers
type: object
required:
- count
- data
properties:
count:
type: integer
description: The number of transfers returned
data:
type: array
minItems: 0
items:
$ref: '#/components/schemas/TransferResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/AuthenticationError'
'500':
$ref: '#/components/responses/UnexpectedError'
/transfers/{transferID}:
parameters:
- $ref: '#/components/parameters/TransferIDParameter'
get:
summary: Get a transfer
description: Retrieve a transfer object from the passed in transfer ID
tags:
- Transfers
responses:
'200':
description: Successful transfer object response
content:
application/json:
schema:
$ref: '#/components/schemas/TransferResponse'
examples:
AchOnrampTransferResponse:
$ref: '#/components/examples/AchOnrampTransferResponse'
AchOfframpTransferResponse:
$ref: '#/components/examples/AchOfframpTransferResponse'
AchOfframpWithMemoTransferResponse:
$ref: '#/components/examples/AchOfframpWithMemoTransferResponse'
WireOnrampTransferResponse:
$ref: '#/components/examples/WireOnrampTransferResponse'
WireOfframpTransferResponse:
$ref: '#/components/examples/WireOfframpTransferResponse'
SepaOnrampTransferResponse:
$ref: '#/components/examples/SepaOnrampTransferResponse'
SepaOfframpTransferResponse:
$ref: '#/components/examples/SepaOfframpTransferResponse'
PixOnrampTransferResponse:
$ref: '#/components/examples/PixOnrampTransferResponse'
PixOfframpTransferResponse:
$ref: '#/components/examples/PixOfframpTransferResponse'
SpeiOnrampTransferResponse:
$ref: '#/components/examples/SpeiOnrampTransferResponse'
SpeiOfframpTransferResponse:
$ref: '#/components/examples/SpeiOfframpTransferResponse'
BreBOnrampTransferResponse:
$ref: '#/components/examples/BreBOnrampTransferResponse'
BreBOfframpTransferResponse:
$ref: '#/components/examples/BreBOfframpTransferResponse'
CoBankTransferOnrampTransferResponse:
$ref: '#/components/examples/CoBankTransferOnrampTransferResponse'
CoBankTransferOfframpTransferResponse:
$ref: '#/components/examples/CoBankTransferOfframpTransferResponse'
'401':
$ref: '#/components/responses/AuthenticationError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/UnexpectedError'
put:
summary: Update a transfer
description: Update a transfer that was previously created. Must be in the awaiting_funds state.
tags:
- Transfers
requestBody:
description: Transfer object to be updated
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransferUpdateRequest'
responses:
'201':
description: Transfer object created
content:
application/json:
schema:
$ref: '#/components/schemas/TransferResponse'
examples:
AchOnrampTransferResponse:
$ref: '#/components/examples/AchOnrampTransferResponse'
AchOfframpTransferResponse:
$ref: '#/components/examples/AchOfframpTransferResponse'
AchOfframpWithMemoTransferResponse:
$ref: '#/components/examples/AchOfframpWithMemoTransferResponse'
WireOnrampTransferResponse:
$ref: '#/components/examples/WireOnrampTransferResponse'
WireOfframpTransferResponse:
$ref: '#/components/examples/WireOfframpTransferResponse'
SepaOnrampTransferResponse:
$ref: '#/components/examples/SepaOnrampTransferResponse'
SepaOfframpTransferResponse:
$ref: '#/components/examples/SepaOfframpTransferResponse'
PixOnrampTransferResponse:
$ref: '#/components/examples/PixOnrampTransferResponse'
PixOfframpTransferResponse:
$ref: '#/components/examples/PixOfframpTransferResponse'
SpeiOnrampTransferResponse:
$ref: '#/components/examples/SpeiOnrampTransferResponse'
SpeiOfframpTransferResponse:
$ref: '#/components/examples/SpeiOfframpTransferResponse'
BreBOnrampTransferResponse:
$ref: '#/components/examples/BreBOnrampTransferResponse'
BreBOfframpTransferResponse:
$ref: '#/components/examples/BreBOfframpTransferResponse'
CoBankTransferOnrampTransferResponse:
$ref: '#/components/examples/CoBankTransferOnrampTransferResponse'
CoBankTransferOfframpTransferResponse:
$ref: '#/components/examples/CoBankTransferOfframpTransferResponse'
'401':
$ref: '#/components/responses/AuthenticationError'
'400':
$ref: '#/components/responses/BadRequestError'
'403':
$ref: '#/components/responses/TransferAmlError'
'500':
$ref: '#/components/responses/UnexpectedError'
delete:
summary: Delete a transfer
description: Delete a transfer that was previously created. Must be in the awaiting_funds state.
tags:
- Transfers
responses:
'200':
description: Successful deletion of transfer
'401':
$ref: '#/components/responses/AuthenticationError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/UnexpectedError'
/transfers/{transferID}/execute:
parameters:
- $ref: '#/components/parameters/TransferIDParameter'
post:
summary: Execute a pending USDT trade on a transfer
description: 'Force-executes a stuck USDT-to-USD trade at the current market rate. The transfer must have a pending trade (i.e. appear in `GET /transfers/pending`).
After execution, the transfer will continue processing normally with the executed market rate.
'
tags:
- Transfers
parameters:
- $ref: '#/components/parameters/IdempotencyKeyParameter'
responses:
'200':
description: Transfer with trade execute at market rate enabled successfully
content:
application/json:
schema:
$ref: '#/components/schemas/TransferResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/AuthenticationError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/UnexpectedError'
/transfers/static_templates:
get:
summary: Get all static templates
tags:
- Transfers
parameters:
- $ref: '#/components/parameters/LimitParameter'
- $ref: '#/components/parameters/TransferStartingAfterParameter'
- $ref: '#/components/parameters/TransferEndingBeforeParameter'
responses:
'200':
description: List of static templates (the returned list is empty if none found). Static templates are transfers that are used as templates for other transfers and can be created using the static_templates feature flag.
content:
application/json:
schema:
title: Static Templates
type: object
required:
- count
- data
properties:
count:
type: integer
description: The number of static templates returned
data:
type: array
minItems: 0
items:
$ref: '#/components/schemas/TransferResponse'
examples:
TransfersFound:
summary: A non-empty list of static templates
value:
count: 2
data:
- $ref: '#/components/examples/AchOnrampFundsReceivedTransferResponse'
- $ref: '#/components/examples/AchOfframpTransferResponse'
NoTransfersFound:
summary: An empty list of static templates
value:
count: 0
data: []
'401':
$ref: '#/components/responses/AuthenticationError'
'500':
$ref: '#/components/responses/UnexpectedError'
components:
responses:
AuthenticationError:
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
MissingTokenError:
summary: No Api-Key header
description: The header may be missing or misspelled.
value:
code: required
location: header
name: Api-Key
message: Missing Api-Key header
InvalidTokenError:
summary: Invalid key in Api-Key header
value:
code: invalid
location: header
name: Api-Key
message: Invalid Api-Key header
NotFoundError:
description: No resource found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
NotFoundErrorExample:
summary: Invalid customer id
value:
code: Invalid
message: Unknown customer id
UnexpectedError:
description: Unexpected error. User may try and send the request again.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
UnexpectedError:
summary: An unexpected error
value:
errors:
- code: unexpected
message: An expected error occurred, you may try again later
ResourceStateConflictError:
description: The requested resource is temporarily in a conflicting state. Retry the same request later with the same idempotency key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
ResourceStateConflictErrorExample:
summary: Balance lock contention while creating a transfer
value:
code: resource_state_conflict
message: Another transfer or balance update is currently in progress for this funding source. Please retry this request.
TransferAmlError:
description: The transfer has failed due to an AML violation (anti-money laundering). Reach out to Bridge for more information
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
TransferAmlErrorExample:
summary: An AML violation error response
value:
code: aml_violation
message: Failed AML Screening
BadRequestError:
description: Request containing missing or invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
BadCustomerRequestErrorExample:
summary: Bad customer request
value:
code: bad_customer_request
message: fields missing from customer body.
name: first_name,ssn
schemas:
TravelRuleIsSelf:
type: boolean
description: Set to `true` when this party is the same person or business as the Bridge customer on the resource. When `true`, Bridge uses the customer's name and address on file instead of relying on `name` and `address` in this payload.
ExchangeDetails:
description: Exchange information for a currency conversion.
properties:
fixed_rate:
description: The target exchange rate.
type: string
estimated_market_rate:
description: The estimated achievable rate based on current market conditions.
type: string
traded_market_rate:
description: The actual effective exchange rate achieved.
type: string
trade_at_market:
description: Whether market-rate execution has been applied to this trade.
type: boolean
updated_at:
description: Timestamp of the last exchange details update.
type: string
format: date-time
client_reference_id:
description: A client-provided reference ID that uniquely identifies a resource in the client's system
type: string
minLength: 1
maxLength: 256
TravelRuleOriginator:
type: object
description: Travel Rule details for originator crypto movement.
properties:
is_self:
$ref: '#/components/schemas/TravelRuleIsSelf'
name:
$ref: '#/components/schemas/TravelRuleName'
address:
description: Mailing or legal address of the originator. Usually omitted when `is_self` is `true`.
allOf:
- $ref: '#/components/schemas/TravelRuleAddress'
wallet_type:
$ref: '#/components/schemas/TravelRuleWalletType'
wallet_attested_ownership_at:
$ref: '#/components/schemas/TravelRuleWalletAttestedOwnershipAt'
identifying_information:
allOf:
- $ref: '#/components/schemas/IdentifyingInformation'
description: 'List of identification objects for the originator. Do **not** include `image_front` or `image_back` fields in this context; those are not accepted in Travel Rule submissions.
'
birth_date:
type: string
description: Date of birth in format yyyy-mm-dd.
minLength: 10
maxLength: 10
place_of_birth:
$ref: '#/components/schemas/PlaceOfBirthInput'
legal_entity_identifier:
type: string
description: The Legal Entity Identifier (LEI) or equivalent (e.g. VAT number) of the originator. Provide this when the originator is a legal entity rather than an individual.
TransferInitiationAuthFactor:
type: object
required:
- category
- authenticated_at
- reference
properties:
category:
description: 'The type of authentication factor used. Must be one of: `knowledge` (something only the user knows, e.g. a PIN or password), `possession` (something only the user has, e.g. a phone receiving an OTP or a hardware token), or `inherence` (something the user is, e.g. a fingerprint or face scan). When `outcome` is `sca_used`, the two factors in `auth_factors` must belong to two different categories.'
type: string
enum:
- knowledge
- possession
- inherence
authenticated_at:
description: The ISO 8601 timestamp when this factor was authenticated.
type: string
format: date-time
reference:
description: Your internal identifier for this authentication event (e.g. a session ID, transaction ID, or audit log reference). Used for reconciliation; Bridge does not validate its format.
type: string
TransferRouteResponse:
required:
- state
- notes
properties:
state:
type: string
enum:
- valid
- invalid
notes:
type: array
items:
type: string
TransferSourcePaymentRail:
type: string
enum:
- ach
- wire
- ach_push
- ach_same_day
- fednow
- arbitrum
- avalanche_c_chain
- base
- bre_b
- co_bank_transfer
- bridge_wallet
- celo
- ethereum
- faster_payments
- optimism
- pix
- polygon
- sepa
- solana
- spei
- stellar
- swift
- tempo
- tron
ReturnInstructions:
description: Optional instructions for where to send funds if the transfer is returned (e.g. refund). Only supported when the source payment rail is crypto. Memo is required when the source payment rail is Stellar.
type: object
required:
- address
properties:
address:
description: The crypto wallet address to send returned funds to. Must be valid for the source payment rail's chain.
type: string
memo:
description: Memo to include with the return transaction. Required when the source payment rail is Stellar; optional for other memo-capable chains.
type: string
CoBankTransferDocumentType:
description: 'Colombian document type identifier. `cc` = Cédula de Ciudadanía, `ce` = Cédula de Extranjería, `nit` = NIT (tax ID), `rut` = RUT (worker registration), `pa` = Passport, `ppt` = Permiso de Protección Temporal.
'
type: string
enum:
- cc
- ce
- nit
- rut
- pa
- ppt
- ti
- rc
- te
- die
- nd
TransferDestination:
required:
- currency
- payment_rail
properties:
currency:
description: When `eur` is specified as the destination currency, the destination rail must be `sepa`.
$ref: '#/components/schemas/EuroInclusiveCurrency'
payment_rail:
description: When `sepa` is specified as the destination payment rail, the destination currency must be `eur`; when `swift` is specified as the destination payment rail, the destination currency must be `usd`.
$ref: '#/components/schemas/SepaSwiftInclusiveOfframpPaymentRail'
external_account_id:
description: External bank account Bridge should send the funds to. The currency associated with the External Account must match the destination currency.
$ref: '#/components/schemas/Id'
bridge_wallet_id:
description: The Bridge Wallet to which Bridge will send the funds. The chain associated with the Bridge Wallet must match the destination payment rail.
$ref: '#/components/schemas/Id'
omad:
$ref: '#/components/schemas/Omad'
readOnly: true
imad:
$ref: '#/components/schemas/Imad'
readOnly: true
trace_number:
$ref: '#/components/schemas/TraceNumber'
readOnly: true
end_to_end_id:
$ref: '#/components/schemas/EndToEndId'
readOnly: true
wire_message:
$ref: '#/components/schemas/WireMessage'
sepa_reference:
$ref: '#/components/schemas/SepaReference'
swift_reference:
$ref: '#/components/schemas/SwiftReference'
spei_reference:
$ref: '#/components/schemas/SpeiReference'
reference:
$ref: '#/components/schemas/Reference'
swift_charges:
description: '**Deprecated**: prefer `charge_bearer`; this field will be removed in a future release. In responses, this field always mirrors `charge_bearer`. Sending both `swift_charges` and `charge_bearer` with conflicting values on a request is rejected.
Which party will bear the charges for the SWIFT transaction. When left blank, `sha` will be used as the default.
'
deprecated: true
$ref: '#/components/schemas/SwiftCharges'
charge_bearer:
description: Which party bears the charges for the SWIFT transaction. Defaults to `sha` when not specified. Replaces the deprecated `swift_charges` field; accepted on both request and response.
$ref: '#/components/schemas/ChargeBearer'
ach_reference:
$ref: '#/components/schemas/AchReference'
uetr:
$ref: '#/components/schemas/Uetr'
blockchain_memo:
type: string
description: The memo to include when sending funds on chain. Only allowed for blockchains that support memos such as Stellar
deposit_id:
$ref: '#/components/schemas/DepositId'
tracking_number:
$ref: '#/components/schemas/TrackingNumber'
readOnly: true
transaction_id:
$ref: '#/components/schemas/TransactionId'
readOnly: true
sending_institution_name:
description: The name of the institution sending the funds
type: string
readOnly: true
TransactionId:
description: 'Deprecated: use tracking_number instead. The unique transaction identifier for this payment.'
type: string
deprecated: true
PaymentRail:
type: string
enum:
- ach
- wire
- ach_push
- ach_same_day
- arbitrum
- avalanche_c_chain
- base
- bre_b
- co_bank_transfer
- celo
- ethereum
- optimism
- pix
- polygon
- solana
- spei
- stellar
- tempo
TransferState:
type: string
enum:
- awaiting_funds
- in_review
- funds_received
- payment_submitted
- payment_processed
- canceled
- undeliverable
- returned
- refund_in_flight
- refund_failed
- refunded
Clabe:
description: The 18-digit CLABE (Clave Bancaria Estandarizada) of the sender who initiated this SPEI transaction
type: string
pattern: ^[0-9]+$
minLength: 18
maxLength: 18
TravelRuleWalletType:
type: string
description: Indicates the custody model for the wallet. Use `self_custodied` for customer-owned wallets (customer controls private keys), `hosted` for wallets managed by a developer or regulated entity on behalf of the customer, or `external` for wallets belonging to external exchanges or smart contracts.
enum:
- hosted
- external
- self_custodied
TrackingNumber:
description: The primary tracking identifier for this fiat transaction. Format varies by payment rail (e.g., UETR for SEPA/FPS, clave de rastreo for SPEI, end-to-end ID for PIX).
type: string
readOnly: true
PixReference:
title: Pix
type: string
minLength: 1
maxLength: 100
TransferInitiationSca:
type: object
required:
- outcome
properties:
outcome:
description: 'Whether Strong Customer Authentication (SCA) was applied or which regulatory exemption or non-applicability reason covers this payment. Use `sca_used` when the user authenticated with SCA. Otherwise, choose the value that applies: `payment_to_self` — payer and payee are the same person (remote only); `trusted_beneficiaries` — payee is on the user''s pre-approved list; `recurring_transaction` — amount and payee match a previously SCA-authorized recurring series; `contactless_low_value` — contactless card payment below the low-value threshold (non-remote only); `unattended_terminal_for_transport` — automated terminal for transport fares or parking (non-remote only); `low_value` — remote payment below the low-value threshold (remote only); `secure_corporate_payment` — dedicated corporate payment process with controls equivalent to SCA (remote only); `transaction_risk_analysis` — PSP has performed real-time risk analysis and the transaction falls within permitted thresholds (remote only); `merchant_initiated_transaction` — payment triggered by the merchant without the payer present, on a pre-authorized mandate (remote only); `not_applicable` — this flow requires initiation context but SCA and SCA exemptions do not apply; `other` — another recognized exemption not listed above.'
type: string
enum:
- sca_used
- payment_to_self
- trusted_beneficiaries
- recurring_transaction
- contactless_low_value
- unattended_terminal_for_transport
- low_value
- secure_corporate_payment
- transaction_risk_analysis
- merchant_initiated_transaction
- not_applicable
- other
auth_factors:
description: Authentication factor metadata. Optional when `outcome` is `sca_used`; if provided, it must contain at least two entries from different `category` values (e.g. one `possession` factor and one `knowledge` factor). Omit this field for any other outcome.
type: array
minItems: 2
items:
$ref: '#/components/schemas/TransferInitiationAuthFactor'
EndToEndId:
description: The end-to-end ID of the FedNow transaction, assigned by the sending bank, and is not guaranteed to be unique across payments.
type: string
TransferResponse:
required:
- id
- amount
- developer_fee
- currency
- on_behalf_of
- source
- destination
- state
- receipt
- created_at
- updated_at
properties:
id:
$ref: '#/components/schemas/Id'
readOnly: true
client_reference_id:
$ref: '#/components/schemas/client_reference_id'
amount:
description: 'Amount of the transfer
# --- truncated at 32 KB (101 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bridge/refs/heads/main/openapi/bridge-transfers-api-openapi.yml