Skip to main content
Store custom key-value pairs on transfers to track your own references like invoice IDs, customer IDs, or order numbers. Use metadata to connect transfers with your internal systems for reconciliation, reporting, and business intelligence.
Status: Not yet implementedThe metadata field is defined in the API spec but is not currently functional. This documentation describes the intended behavior once implementation is complete.

​
Constraints and limitations

PropertyConstraint
Maximum key-value pairs5 per transfer
Maximum key length100 characters
Maximum value length100 characters
ImmutableYes (cannot be updated or deleted)
Searchable/filterableNo
Included in webhook eventsNo
Never store sensitive data like passwords, account numbers, or PII in metadata.

​
Usage

To add metadata, send your key-value pairs when using Create a Transfer. Include the optional metadata field in your request body. Request: 
{
  "source": {
    "accountId": "account_123",
    "asset": "usd"
  },
  "target": {
    "email": "user@example.com",
    "asset": "usd"
  },
  "amount": "100.00",
  "asset": "usd",
  "execute": true,
  "metadata": {
    "invoiceId": "INV-001",
    "customerId": "cust_123"
  }
}
Response: 
{
  "transferId": "transfer_123",
  "status": "processing",
  "metadata": {
    "invoiceId": "INV-001",
    "customerId": "cust_123"
  },
  ...
}

​
Retrieving metadata

Metadata is included automatically when you retrieve transfers. No additional API calls are needed. Get a single transfer: 
GET /v2/transfers/{transferId}
List all transfers: 
GET /v2/transfers
Example response: 
{
  "transferId": "transfer_123",
  "status": "completed",
  "metadata": {
    "invoiceId": "INV-001",
    "customerId": "cust_123"
  },
  ...
}
The metadata persists throughout the transfer lifecycle and is returned in all subsequent API calls.

​
Best practices

  • Use consistent key names across transfers (invoiceId not invoice_id) for easier querying in your own systems
  • Store IDs, not full data to reference your system’s records instead of duplicating information
  • Prioritize your most important 5 fields since you’re limited to 5 key-value pairs per transfer