Currency Send Destinations API

New API endpoint to get available currency send destinations. This supplements your existing currency send system by providing the list of destinations players can send currency to. No changes to existing APIs.

Addition to Existing System

  • • New API: /api/currency-sends/available-destinations
  • • Existing APIs unchanged: /initiate-send, /claim-currency
  • • Optional integration: Use to improve UX, not required for sends to work
  • • Backward compatible: Your current send implementation continues working
POST

/api/currency-sends/available-destinations

Get the destinations that players can send currency to

Same Authentication

Uses the same authentication as your existing currency send endpoints:

X-Game-Secret-Key: your_game_secret_key_here

Request Body

{
  "source_game_id": "123456789012"
}

Response

{
  "status": "success",
  "available_games": [...],
  "total_destinations": 5
}

Integration Patterns

Pattern 1: Add to Existing UI (Recommended)

Call this API to populate your existing destination selection dropdown. Your current send flow remains unchanged.

Before: Hard-coded destination list or manual game ID entry
After: Dynamic destination list from API, same send process

Pattern 2: Pre-Send Validation

Initiate validates the amount against the sending title's currency limits, not the destination's, so validate against your own currency's minimum and maximum before calling /initiate-send. The destination's minimum_transfer / maximum_transfer are for display only.

Benefit: Prevent failed sends due to amount limits, better user feedback

Pattern 3: Optional Caching (Performance)

Cache the response for better performance. Call once daily and store locally.

Optional: Only implement if you want instant UI loading

Complete Response Example

{
  "status": "success",
  "source_game_id": "123456789012",
  "source_game_name": "Adventure Quest",
  "source_game_icon": "https://cdn.invo.network/icons/adventure-quest.png",
  "source_currency_name": "Gold",
  "source_currency_icon": "https://cdn.invo.network/currency/gold.png",
  "universal_transfers": "yes",
  "transfer_mode": "universal",
  "available_games": [
    {
      "game_id": "987654321098",
      "game_name": "Space Warriors",
      "tenant_type": "game",
      "developer_name": "Other Studio",
      "publisher_name": "Other Publisher",
      "genre": "Action",
      "platform": "Mobile",
      "game_status": "live",
      "game_icon": "https://cdn.invo.network/icons/space-warriors.png",
      "game_poster": "https://cdn.invo.network/posters/space-warriors.png",
      "game_url": "https://spacewarriors.example.com",
      "game_description": "Fast-paced space combat.",
      "currency_name": "Energy Credits",
      "currency_symbol": "EC",
      "currency_symbol_url": "https://cdn.invo.network/currency/energy-credits.png",
      "minimum_transfer": "5.00",
      "maximum_transfer": "1000.00",
      "accepts_steam_origin_value": true
    }
  ],
  "total_destinations": 1

  // When transfer_mode is "linked", the response also includes:
  // "linked_game_ids": ["987654321098", "456789012345"]
}

Key Points

  • • Your own title is not listed. Same-title sends still work: pass your own game id as receiving_game_id
  • • Limits: a send amount is checked against the sending title's currency limits; the destination's minimum_transfer and maximum_transfer are informational
  • • Destination info: Display game_name and currency_symbol in UI. tenant_type tells you what kind of tenant each destination is
  • • IDs for sending: Use game_id in your existing /initiate-send calls
  • • Platform store titles: a title distributed through a platform store cannot receive currency from a title outside that store, so when your title is outside it those titles are omitted from available_games. Each destination's accepts_steam_origin_value says whether it accepts currency bought through a platform store; read it, and handle 409 STEAM_VALUE_NON_TRANSFERABLE at initiate

Minimal Integration Examples

Server-side only. This call takes your title's X-Game-Secret-Key, which must never ship in a game or app client (Unity, Unreal, Godot, web or mobile). Your client asks your server, and your server makes this call. See Credentials & Key Handling.

Node.js (server)

// Node (server). INVO_GAME_SECRET comes from your server's environment.
const res = await fetch('https://invo.network/api/currency-sends/available-destinations', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Game-Secret-Key': process.env.INVO_GAME_SECRET,
  },
  body: JSON.stringify({ source_game_id: '123456789012' }),
});
const data = await res.json();
// Serve the list to your clients from your server.

Python (server)

# Python (server)
import os, requests
r = requests.post(
    "https://invo.network/api/currency-sends/available-destinations",
    headers={"X-Game-Secret-Key": os.environ["INVO_GAME_SECRET"]},
    json={"source_game_id": "123456789012"},
    timeout=15,
)
data = r.json()
# Serve the list to your clients from your server.

Migration Strategy

Phase 1: Add Destinations API (Optional)

  • • Add the new destinations endpoint call
  • • Use response to populate existing destination selection UI
  • • Keep all existing send logic unchanged

Phase 2: Add Validation (Optional)

  • • Validate amounts against your own currency's min/max before calling your existing send APIs
  • • Provide better user feedback

Phase 3: Add Caching (Optional)

  • • Cache destinations response for 24 hours
  • • Improve performance by avoiding repeated API calls
  • • Add manual refresh option

Benefits of Integration

User Experience

  • • Dynamic destination list instead of hard-coded options
  • • Real-time transfer limits and validation
  • • Clear destination names and currency info
  • • Reduced failed sends due to invalid destinations

Developer Benefits

  • • No manual destination list maintenance
  • • Automatic new destination discovery
  • • Centralized transfer policy management
  • • Better error prevention

Performance

  • • Optional caching for instant UI loading
  • • Reduced failed API calls
  • • Better network efficiency
  • • Graceful fallback options

Ecosystem

  • • Automatic support for new destinations
  • • Respect for universal vs linked transfer modes
  • • Future-proof implementation

Frequently Asked Questions

Do I need to change my existing send APIs?

No. Your existing /initiate-send and /claim-currency endpoints work exactly the same. This is just an additional API to get destination information.

Is this API required for sends to work?

No, it's optional. Your current currency sends will continue working. This API just helps improve the user experience by providing dynamic destination lists and validation data.

How often should I call this API?

Once per day is sufficient. Destination lists don't change frequently. You can cache the response and refresh daily, or call it each time a player opens the send UI (but caching is more efficient).

Will my own title appear in the destinations list?

No. Your own title is left out of the list. Same-title peer-to-peer sends still work: use your own game id as the receiving_game_id.

What happens if the destinations API is unavailable?

Your existing send functionality continues working. You can implement fallback logic (cached data, a default destination list, or manual game ID entry) while the destinations API is unavailable.