Deposit Intents

A Deposit Intent configures where a user’s deposits should be routed. It creates a unique deposit address and stores the destination chain, token, and recipient address.

Create Deposit Intent

Create or update a deposit intent for a user. Endpoint: POST /api/deposit-intents Authentication: Required (API Key)

Request

Headers:

x-api-key: your_api_key
Content-Type: application/json

Body:

{
  "userId": "string",
  "targetChainId": number,
  "targetTokenAddress": "string",
  "targetAddress": "string"
}

Parameters:

Field	Type	Required	Description
`userId`	string	Yes	Unique identifier for your user
`targetChainId`	number	Yes	Destination chain ID (e.g., 137 for Polygon)
`targetTokenAddress`	string	Yes	EVM address of target token
`targetAddress`	string	Yes	EVM address to receive funds

Response

Status: 200 OK or 201 Created

{
  "userId": "user-123",
  "depositAddress": "0xABC...123",
  "targetChainId": 137,
  "targetChainKey": "polygon",
  "targetTokenAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "targetAddress": "0x5555555555555555555555555555555555555555",
  "protocolFeeBps": 50,
  "sponsoredGas": false,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Response Fields:

Field	Type	Description
`userId`	string	User identifier
`depositAddress`	string	Unique address for user to send deposits
`targetChainId`	number	Destination chain ID
`targetChainKey`	string	Human-readable chain identifier
`targetTokenAddress`	string	Token address on destination chain
`targetAddress`	string	Recipient address on destination chain
`protocolFeeBps`	number	Protocol fee in basis points (from your API key)
`sponsoredGas`	boolean	Whether gas is sponsored (from your API key)
`createdAt`	string	ISO 8601 timestamp of creation
`updatedAt`	string	ISO 8601 timestamp of last update

Example

Request:

curl -X POST https://api.bridgfy.com/api/deposit-intents \
  -H "x-api-key: bfy_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-abc-123",
    "targetChainId": 137,
    "targetTokenAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
    "targetAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8"
  }'

Response:

{
  "userId": "user-abc-123",
  "depositAddress": "0x1234567890123456789012345678901234567890",
  "targetChainId": 137,
  "targetChainKey": "polygon",
  "targetTokenAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "targetAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8",
  "protocolFeeBps": 50,
  "sponsoredGas": false,
  "createdAt": "2024-01-01T10:30:00.000Z",
  "updatedAt": "2024-01-01T10:30:00.000Z"
}

Error Responses

Invalid Chain ID Status: 400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid target chain ID: 999",
  "error": "Bad Request"
}

Invalid Address Status: 400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid EVM address format",
  "error": "Bad Request"
}

Blacklisted Token Status: 400 Bad Request

{
  "statusCode": 400,
  "message": "Token is blacklisted",
  "error": "Bad Request"
}

Unauthorized Status: 401 Unauthorized

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

Get Deposit Intent

Retrieve the active deposit intent for a user. Endpoint: GET /api/users/:userId/deposit-intent Authentication: Required (API Key)

Request

Headers:

x-api-key: your_api_key

Path Parameters:

Parameter	Type	Description
`userId`	string	User identifier

Response

Status: 200 OK

{
  "userId": "user-123",
  "depositAddress": "0xABC...123",
  "targetChainId": 137,
  "targetChainKey": "polygon",
  "targetTokenAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "targetAddress": "0x5555555555555555555555555555555555555555",
  "protocolFeeBps": 50,
  "sponsoredGas": false,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Example

Request:

curl https://api.bridgfy.com/api/users/user-abc-123/deposit-intent \
  -H "x-api-key: bfy_your_api_key"

Response:

{
  "userId": "user-abc-123",
  "depositAddress": "0x1234567890123456789012345678901234567890",
  "targetChainId": 137,
  "targetChainKey": "polygon",
  "targetTokenAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "targetAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8",
  "protocolFeeBps": 50,
  "sponsoredGas": false,
  "createdAt": "2024-01-01T10:30:00.000Z",
  "updatedAt": "2024-01-01T10:30:00.000Z"
}

Error Responses

Not Found Status: 404 Not Found

{
  "statusCode": 404,
  "message": "Deposit intent not found for user: user-123",
  "error": "Not Found"
}

Unauthorized Status: 401 Unauthorized

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

Understanding Deposit Intents

One Intent Per User

Each userId can have one active Deposit Intent. Creating a new intent for the same user updates the existing one. Important: The depositAddress remains the same even when updating the intent. Only the routing destination changes.

Fee Snapshotting

When you create a deposit intent, fee settings are captured from your API key:

protocolFeeBps - Snapshotted at creation
sponsoredGas - Snapshotted at creation

This means: Even if you later change your API key’s fee settings, existing deposit intents keep their original fee configuration. To update fees for a user: Create a new deposit intent (which updates the existing one with new fee settings).

Deposit Address Stability

The depositAddress is:

Deterministic - Based on the user’s userId
Stable - Same address across all supported chains
Reusable - Can be used for multiple deposits
Persistent - Doesn’t change when you update the intent

Supported Chains

Valid targetChainId values:

Chain	Chain ID	Key
Base	8453	`base`
Ethereum	1	`ethereum`
Polygon PoS	137	`polygon`
Arbitrum One	42161	`arbitrum`
Avalanche C-Chain	43114	`avalanche`

Token Addresses

The targetTokenAddress must be a valid EVM address:

For native tokens (ETH, MATIC, AVAX): Use 0x0000000000000000000000000000000000000000
For ERC-20 tokens: Use the token contract address on the destination chain

Example:

USDC on Polygon: 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174
USDC on Ethereum: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48

Note: Token addresses differ across chains. Make sure to use the correct address for your target chain.

Workflow

Typical Integration Flow

User signs up in your application
Create deposit intent with their preferred destination
Show deposit address to the user in your UI
User sends funds to the deposit address
Bridgfy detects deposit automatically via webhook
Funds are routed to the destination specified in the intent
Track execution via the Executions API

Updating Destinations

If a user wants to change their destination:

Call the same endpoint POST /api/deposit-intents with the same userId
Provide new destination parameters
Intent is updated with new routing configuration
Deposit address remains the same

Important: Future deposits will use the new destination. Previously initiated deposits continue with their original routing.

Testing

Before going to production:

Use the Simulation API to verify routes exist
Test with testnet chains and tokens
Verify fee calculations match expectations
Test updating intents (same userId, different destination)

Best Practices

User ID Selection

Choose a userId that:

Is unique across your entire user base
Is stable (doesn’t change if user updates profile)
Is not guessable or sequential (use UUIDs)

Good examples:

uuid-abc-123-def-456
user_clerkId_abc123
Hash of email + salt

Bad examples:

1, 2, 3 (sequential)
[email protected] (PII)
user123 (potentially guessable)

Error Handling

Always handle potential errors:

try {
  const intent = await createDepositIntent({
    userId: user.id,
    targetChainId: 137,
    targetTokenAddress: '0x...',
    targetAddress: user.walletAddress
  });
  
  // Show deposit address to user
  displayDepositAddress(intent.depositAddress);
  
} catch (error) {
  if (error.status === 400) {
    // Invalid parameters - check chain ID, addresses
    showError('Invalid configuration. Please check your wallet address.');
  } else if (error.status === 401) {
    // Auth error - check API key
    logError('API key invalid or expired');
  } else {
    // Other errors
    showError('Unable to create deposit address. Please try again.');
  }
}

Validation

Before creating an intent:

Validate addresses - Ensure they’re valid EVM addresses
Validate chain ID - Confirm it’s a supported chain
Check token support - Use simulation to verify the token can be routed
Communicate clearly - Show users what they’re configuring

Next Steps

Use the Routing API to simulate deposits before creating intents
Learn about Executions to track deposit status
Review Error Codes for troubleshooting

Get Started

Core Concepts

Integration Guides

API Reference

Deposit intents

Deposit Intents

Create Deposit Intent

Request

Response

Example

Error Responses

Get Deposit Intent

Request

Response

Example

Error Responses

Understanding Deposit Intents

One Intent Per User

Fee Snapshotting

Deposit Address Stability

Supported Chains

Token Addresses

Workflow

Typical Integration Flow

Updating Destinations

Testing

Best Practices

User ID Selection

Error Handling

Validation

Next Steps

Get Started

Core Concepts

Integration Guides

API Reference

​Deposit Intents

​Create Deposit Intent

​Request

​Response

​Example

​Error Responses

​Get Deposit Intent

​Request

​Response

​Example

​Error Responses

​Understanding Deposit Intents

​One Intent Per User

​Fee Snapshotting

​Deposit Address Stability

​Supported Chains

​Token Addresses

​Workflow

​Typical Integration Flow

​Updating Destinations

​Testing

​Best Practices

​User ID Selection

​Error Handling

​Validation

​Next Steps

Deposit Intents

Create Deposit Intent

Request

Response

Example

Error Responses

Get Deposit Intent

Request

Response

Example

Error Responses

Understanding Deposit Intents

One Intent Per User

Fee Snapshotting

Deposit Address Stability

Supported Chains

Token Addresses

Workflow

Typical Integration Flow

Updating Destinations

Testing

Best Practices

User ID Selection

Error Handling

Validation

Next Steps