Entity Balance

Understanding entity balance management in the Rise ecosystem

Entity balance management in Rise tracks funds on the blockchain for users, teams, and companies. Every entity has an associated balance that can be queried using their unique identifier.

Entity Balance API

Get Entity Balance

Retrieve the current balance for a specific entity:

curl -X GET "${this.baseUrl}/v2/balance?nanoid=te-abc123def456" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "success": true,
  "data": {
    "rise_account_address": "0x1234567890abcdef...",
    "balances": [
      {
        "currency": "USD",
        "balance_cents": 100000
      },
      {
        "currency": "EUR",
        "balance_cents": 50000
      }
    ]
  }
}

Supported Currencies

You can specify which currencies to query:

curl -X GET "${this.baseUrl}/v2/balance?nanoid=te-abc123def456&currencies=USD,EUR" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Balance Components

Available Balance

Funds that can be used for payments and transactions

Currency Support

Multiple currencies supported (USD, EUR, etc.)

Precision

All amounts returned in cents for precision

Real-time

Balances updated in real-time from blockchain

Authorization Requirements

Different entity types have different authorization requirements:

Team Balance Access

• Team Admin: Full access to team balance
• Team Finance Admin: Full access to team balance
• Team Viewer: Read-only access to team balance
• Team Employee: No access to team balance

Company Balance Access

• Company Owner: Full access to company balance
• Org Admin: Full access to company balance
• Org Finance Admin: Full access to company balance
• Org Viewer: Read-only access to company balance

User Balance Access

• User: Can only access their own balance
• Others: No access to user balance

Integration Example

class RiseEntityBalance {
  constructor(baseUrl, jwtToken) {
    this.baseUrl = baseUrl;
    this.headers = {
      'Authorization': `Bearer ${jwtToken}`,
      'Content-Type': 'application/json'
    };
  }

  async getBalance(nanoid, currencies = null) {
    const params = new URLSearchParams({ nanoid });
    if (currencies) {
      params.append('currencies', currencies.join(','));
    }
    
    const response = await fetch(
      `${this.baseUrl}/v2/balance?${params}`,
      { headers: this.headers }
    );
    return response.json();
  }
}

// Usage example
const balanceApi = new RiseEntityBalance(
  'https://b2b-api.riseworks.io', // or your environment URL
  'your-jwt-token'
);

Error Handling

Common errors when working with entity balances:

HTTP Status	Description	Solution
400	Bad Request - Invalid nanoid format	Ensure nanoid follows correct format
401	Unauthorized - Invalid JWT token	Re-authenticate to get a valid JWT
403	Forbidden - Insufficient permissions	Check user permissions for the entity
404	Not Found - Entity doesn’t exist	Verify the nanoid exists in the system
500	Internal Server Error	Retry the request or contact support

Common Error Scenarios

Invalid Nanoid Format (400):

{
  "success": false,
  "data": "Invalid nanoid format: must start with te-, co-, or us-"
}

Entity Not Found (404):

{
  "success": false,
  "data": "No entity found with nanoid te-invalid123"
}

Permission Denied (403):

{
  "success": false,
  "data": "User us-abc123def456 must have admin access to team te-xyz789abc123. Current role: team_employee"
}

Security Considerations

Always verify entity ownership and permissions before accessing balance information. Only authorized users should have access to entity balances.

• Permission Validation: Ensure users have proper permissions to access entity balances
• Rate Limiting: Implement appropriate rate limiting for balance queries
• Audit Logging: Log all balance access for security auditing

Related Concepts

Entity Nanoid

Understanding nanoid identifiers

Teams

Team management concepts

Payments

Payment processing and flows

Permissions

Understanding access control

Balance Precision: All balance amounts are returned in cents to maintain precision. Convert to decimal format only when displaying to users.