Internal Transfer Endpoints¶

This section covers API endpoints related to internal transfers between users. Internal transfer operations allow users to send funds to other users within the platform, as well as receive funds from other platform users. These transfers are executed instantly without blockchain or external banking fees, providing a cost-effective way to move funds between platform accounts.

Create Internal Transfer¶

Initiates a transfer from the authenticated user to another user.

POST /internal-transfer

Required Permissions¶

• allow_transfer

Rate Limit¶

600 requests per minute

Request Parameters¶

Example Request¶

{
  "currency_code": "BTC",
  "amount": "0.01000000",
  "recipient": "user123",
  "callback_url": "https://example.com/callbacks/transfers",
  "custom_id": "my-transfer-123",
  "note": "Payment for services"
}

Response¶

{
  "code": "TRF123456",
  "custom_id": "my-transfer-123",
  "callback_url": "https://example.com/callbacks/transfers",
  "created_at": "2023-01-15T14:30:15Z",
  "updated_at": "2023-01-15T14:30:15Z",
  "done_at": null,
  "timestamp": "2023-01-15T14:30:15Z",
  "status": "pending",
  "reason_code": null,
  "reason_message": null,
  "currency_code": "BTC",
  "amount": "0.01000000",
  "fee_amount": "0.00000000",
  "sender": "user456",
  "recipient": "user123",
  "note": "Payment for services"
}

Response Fields¶

List Internal Transfers¶

Returns a list of internal transfers.

GET /internal-transfer

Required Permissions¶

• allow_transfer

Rate Limit¶

600 requests per minute

Query Parameters¶

Response¶

The API uses a standard offset-based pagination system with limit and offset parameters. The response is a direct array of transfer objects without pagination metadata wrapper.

[
  {
    "code": "TRF123456",
    "custom_id": "my-transfer-123",
    "callback_url": "https://example.com/callbacks/transfers",
    "created_at": "2023-01-15T14:30:15Z",
    "updated_at": "2023-01-15T14:35:20Z",
    "done_at": "2023-01-15T14:35:20Z",
    "timestamp": "2023-01-15T14:35:20Z",
    "status": "success",
    "reason_code": null,
    "reason_message": null,
    "currency_code": "BTC",
    "amount": "0.01000000",
    "fee_amount": "0.00000000",
    "sender": "user456",
    "recipient": "user123",
    "note": "Payment for services"
  }
  // More transfers...
]

Response Fields¶

Same as the create transfer response.

Pagination¶

The API uses simple offset-based pagination with limit and offset parameters. Offset is limited for maximum 10000, if you set more - error will be returned. The default limit is 100, and the maximum limit is 200. The response is a direct list of transfer objects without pagination metadata wrapper. If you need to fetch more than 200 transfers, you should use the start_at and end_at parameters to fetch transfers in smaller date ranges. List is sorted by creation date in descending order.

Get Transfer Details¶

Returns details of a specific transfer.

GET /internal-transfer/{code}

Required Permissions¶

• allow_transfer

Rate Limit¶

600 requests per minute

Path Parameters¶

Response¶

Same as a single transfer object from the list endpoint.

Transfer Status Values¶

Callback Notifications¶

If a callback_url was provided when creating the transfer, the system will send POST requests to this URL when the transfer status changes.

Important Note: You may not receive callbacks for every intermediate status change or field update if changes occur very rapidly. When operations transition through multiple states quickly, intermediate callbacks may be skipped. However, you will always receive callbacks for the final states of operations. Design your callback handling to be idempotent and not dependent on receiving every single state transition.

Currently, callbacks are not signed. The signature mechanism for callbacks is planned for a future update. You should validate callback data by making an authenticated API request to verify the transfer status.

Callback Payload¶

The callback payload contains the same data as the transfer details response, with essential fields for status updates:

{
  "code": "TRF123456",
  "custom_id": "my-transfer-123",
  "created_at": "2023-01-15T14:30:15Z",
  "updated_at": "2023-01-15T14:35:20Z",
  "done_at": "2023-01-15T14:35:20Z",
  "status": "completed",
  "reason_code": null,
  "reason_message": null,
  "currency_code": "BTC",
  "amount": "0.01000000",
  "fee_amount": "0.00000000",
  "sender": "user456",
  "recipient": "user123",
  "note": "Payment for services"
}

Securing Callbacks¶

Since callbacks are not currently signed, you should implement these security measures:

1. Whitelist IPs: Accept callbacks only from the service's IP addresses. Contact support to get the list of server IPs.
2. Verify Data: Always make an authenticated API request to /internal-transfer/{code} to verify the status and details of any transfer after receiving a callback.
3. Use HTTPS: Ensure your callback URL uses HTTPS to encrypt the data in transit.

Common Use Cases¶

• B2B payments: Transfer funds between business partners
• User payments: Transfer funds between your users
• Fund management: Move funds between your own accounts