Entity Balance - Rise B2B API

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

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.

​Entity Balance API

​Get Entity Balance

​Supported Currencies

​Balance Components

Available Balance

Currency Support

Precision

Real-time

​Authorization Requirements

​Team Balance Access

​Company Balance Access

​User Balance Access

​Integration Example

​Error Handling

​Common Error Scenarios

​Security Considerations

​Related Concepts

Entity Nanoid

Teams

Payments

Permissions

Entity Balance API

Get Entity Balance

Supported Currencies

Balance Components

Authorization Requirements

Team Balance Access

Company Balance Access

User Balance Access

Integration Example

Error Handling

Common Error Scenarios

Security Considerations

Related Concepts