Skip to main content

Documentation Index

Fetch the complete documentation index at: https://apidocs.bridge.xyz/llms.txt

Use this file to discover all available pages before exploring further.

Bridge works with various banking partners and financial institutions to realize our Orchestration services. On occasion, these institutions notify Bridge that a fiat deposit was later recalled by the sender and request that the funds be returned if possible. Bridge calls these funds requests. Many — but not all — funds requests are due to fraud or suspected fraud. The API includes a boolean fraud field to indicate whether the recall is fraud-related or non-fraudulent.

​
How Funds Requests Work

Funds requests are tied to deposits, and a deposit_id is provided in the API response. This deposit_id can be cross-referenced in the virtual account event history to determine which customer deposit is impacted.

​
What Happens Operationally

  • If Bridge receives a funds request before the money movement completes, Bridge will automatically attempt to return the funds to the sending fiat account.
  • If the funds request is received after funds have already left Bridge, developers may need to take action using our fiat deposit return API.
  • Bridge Operations will proactively follow up with developers on fraudulent funds requests.
  • Bridge may take remedial action if a developer’s funds request volume exceeds acceptable thresholds.

​
Common Developer Use Cases

Developers typically use the Funds Requests API for:

​
1. Fraud & Compliance Monitoring

  • Identify recalled deposits as suspicious when fraud=true.
  • Flag customers or senders internally for enhanced review.
  • Strengthen fraud detection and compliance workflows.

​
2. Return Reason Visibility

  • When a transaction is returned, query the Funds Requests API to determine whether a funds request was initiated.
  • Surface recall reason context back to the end user (e.g., fraud vs. non-fraud recall).

​
Technical Integration Guidance

​
Polling

Webhooks are currently not supported for funds requests. You should periodically poll the Funds Request endpoint. Recommended best practice:
  • Poll on a recurring cadence appropriate for your risk posture (e.g., every few minutes).
  • Store and deduplicate results internally.
Use deposit_id to:
  • Cross-reference your internal records.
  • Retrieve the associated virtual account event history.
  • Identify the impacted customer and downstream transaction state.

​
Returns API Integration

If you receive a funds request after the transaction has completed, you may need to: Note: If Bridge receives the funds request notification before completion, Bridge will automatically attempt to return the funds.

​
API Examples

​
List All Funds Requests

Request
curl --request GET \
     --url 'https://api.bridge.xyz/v0/funds_requests' \
     --header 'Api-Key: <Api-Key>' \
     --header 'accept: application/json'

​
List All Funds Requests with Filters

Request
curl --request GET \
     --url 'https://api.bridge.xyz/v0/funds_requests?customer_id=123&fraud=true' \
     --header 'Api-Key: <Api-Key>' \
     --header 'accept: application/json'

​
Implementation Summary

When integrating Funds Requests:
  1. Poll the endpoint regularly (no webhooks available).
  2. Link each funds request to its deposit_id.
  3. Treat fraud=true as a compliance signal.
  4. Integrate with the the fiat deposit return API for returning funds
  5. Maintain internal workflows to review and respond to recalls promptly.
Funds requests are a key signal for fraud monitoring, compliance controls, and customer communication.