> ## Documentation Index
> Fetch the complete documentation index at: https://docs.riseworks.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Authenticate and send your first payment in under 10 minutes

This walks through the most common integration pattern end-to-end: a dedicated wallet authenticates *as* a manager on your team/company, then lists teams and sends a payment. Every step is copy-paste runnable.

<Note>
  New here? [Overview](/v1-legacy/overview) explains what this section is and why it exists. This page assumes you just want working code.
</Note>

## Prerequisites

* **An existing Rise team or company** (from before your V1 integration) and its **V1 RiseID** — an address like `0xabc...`, found in the Rise dashboard under company/team settings.
* **A wallet registered as that team/company's Owner or a delegate** — see [Secondary Wallets](/authentication/secondary-wallets) if you need to set one up. This wallet's private key does the signing; it doesn't need any funds.
* **The email of a manager on that team** — a user with the `team_admin`, `team_finance_admin`, `team_delegate_admin`, or `team_payment_initiator` role. Can be the same person who controls the wallet, or someone else.
* **Node.js 16+**

<Tip>
  Don't have those on hand, or not sure what they mean? See [Which flow do I use?](/v1-legacy/authentication#which-flow-do-i-use) — there's also a simpler "personal auth" flow for a wallet tied to your own individual Rise user account.
</Tip>

## Step 1: Install dependencies

```bash theme={null}
mkdir v1-legacy-integration
cd v1-legacy-integration
npm init -y
npm install riseworks-sdk ethers dotenv
```

## Step 2: Configure your environment

Create a `.env` file:

```bash theme={null}
RISE_ENVIRONMENT=prod          # or 'stg' for staging
WALLET_PRIVATE_KEY=0x...       # the delegate/owner wallet's private key
TEAM_RISE_ID=0x...             # your team or company's V1 RiseID
MANAGER_EMAIL=manager@example.com
```

<Warning>
  Never commit `.env` to version control. Anyone with `WALLET_PRIVATE_KEY` can sign on your team/company's behalf.
</Warning>

## Step 3: Authenticate and list your teams

Save this as `quickstart.js` and run it to confirm authentication works end-to-end:

```javascript theme={null}
// quickstart.js
require('dotenv').config();
const { RiseApiClient } = require('riseworks-sdk');
const { ethers } = require('ethers');

async function main() {
  const wallet = new ethers.Wallet(process.env.WALLET_PRIVATE_KEY);

  // jwtToken is required to construct a client, but any placeholder works —
  // updateToken() below replaces it with the real one.
  const client = new RiseApiClient({
    environment: process.env.RISE_ENVIRONMENT || 'prod',
    jwtToken: 'pending',
  });

  console.log('Requesting SIWE message...');
  const { data } = await client.v1Legacy.getSiwe({
    wallet: wallet.address,
    rise_id: process.env.TEAM_RISE_ID,
    impersonate: process.env.MANAGER_EMAIL,
  });

  console.log('Signing message with wallet', wallet.address);
  const signature = await wallet.signMessage(data.message);

  console.log('Verifying signature and exchanging for a JWT...');
  const { data: tokenData } = await client.v1Legacy.verifySiwe({
    wallet: wallet.address,
    message: data.message,
    signature,
  });

  client.updateToken(tokenData.token);
  console.log('Authenticated. Token expires in', tokenData.expires_in, 'seconds.\n');

  console.log('Fetching teams...');
  const teams = await client.v1Legacy.listTeams();
  console.log(`Found ${teams.data.length} team(s):`, teams.data.map((t) => t.riseId));
}

main().catch((err) => {
  console.error('Quickstart failed:', err.message);
  process.exit(1);
});
```

```bash theme={null}
node quickstart.js
```

If this prints at least one team, authentication is working correctly — move on to Step 4. If it fails, jump to [Troubleshooting](#troubleshooting) below.

## Step 4: Send your first payment

Add a payee nanoid or RiseID to your `.env` (any contractor already on the team you listed above), then extend the script:

```bash theme={null}
# add to .env
PAYEE_ID=us-xyz789abc123
```

```javascript theme={null}
// append to quickstart.js, inside main(), after the listTeams() call

console.log('\nSending a test payment...');
const receipt = await client.v1Legacy.pay(
  {
    wallet: wallet.address,
    rise_id: process.env.TEAM_RISE_ID,
    payee: process.env.PAYEE_ID,
    amount: 1000000, // $1.00, in micro-USD (1,000,000 = $1.00) — change before running against prod
    salt: Date.now(), // must be unique per payer+payee+amount — see Step 4 note below
  },
  process.env.WALLET_PRIVATE_KEY, // client has no configured signing key, so pass it explicitly
);

console.log('Payment sent. Transaction hash:', receipt.data.transactionHash);
```

<Warning>
  `salt` must be unique for every payment to the same payee with the same amount — reusing one fails with `409 Conflict`. `Date.now()` is fine for testing; use a counter or UUID-derived integer in production. See [Payments](/v1-legacy/payments#prepare-an-instant-payment).
</Warning>

<Tip>
  Test against **staging** first (`RISE_ENVIRONMENT=stg` and `https://b2b-api.staging-riseworks.io`) before pointing this at production — see [Base URLs](/v1-legacy/overview#base-urls).
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="getSiwe or verifySiwe returns 403" icon="lock">
    Either `wallet` isn't registered as the RiseID's Owner/delegate, or `impersonate` isn't a user with a manager role on that RiseID. Both are checked independently — see [Which flow do I use?](/v1-legacy/authentication#which-flow-do-i-use).
  </Accordion>

  <Accordion title="listTeams()/pay() returns 401" icon="key">
    The JWT is missing or expired (tokens last 24 hours). Re-run the authentication step to get a fresh one, and make sure `client.updateToken(...)` ran before the failing call.
  </Accordion>

  <Accordion title="pay() returns 409 Conflict" icon="triangle-exclamation">
    You reused a `salt` for the same payer + payee + amount. Use a new, never-before-used salt and retry.
  </Accordion>

  <Accordion title="Not sure what format an ID is in" icon="fingerprint">
    Every non-auth identifier (`rise_id`, `payee`, `teamId`, etc.) accepts a V1 RiseID, V2 RiseID, nanoid, or RiseAccount address interchangeably — no conversion needed. See [Identifier formats](/v1-legacy/overview#identifier-formats).
  </Accordion>
</AccordionGroup>

See [Troubleshooting](/v1-legacy/troubleshooting) for the full list of errors across every endpoint.

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/v1-legacy/authentication">
    Full reference for both auth flows, manual HTTP, and error cases
  </Card>

  <Card title="Payments" icon="credit-card" href="/v1-legacy/payments">
    Batch payments, payment intents, and payment history
  </Card>

  <Card title="Teams & Talent" icon="users" href="/v1-legacy/teams">
    List, get, and remove contractors
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/v1-legacy/troubleshooting">
    Common errors and how to fix them, across every endpoint
  </Card>
</CardGroup>