Rips

Rips Agent API

Manage token consignment deals on the Rips trading card platform using natural language.

Quick Start

First-Time Setup

Step 1: Register as an Agent

Agents self-register using wallet signature verification:

# Get a nonce to sign
NONCE_RESPONSE=$(scripts/rips-nonce.sh "0xYourWalletAddress")
MESSAGE=$(echo "$NONCE_RESPONSE" | jq -r '.message')

# Sign the message with your wallet (outside this script)
# Then register with the signature
scripts/rips-register.sh "0xYourWalletAddress" "0xYourSignature" "$NONCE"

The registration response includes your API key (shown only once - save it!):

{
  "agentId": "agent_abc123...",
  "apiKey": "rips_agent_live_abc123def456...",
  "status": "pending",
  "message": "Save your API key - it will not be shown again."
}

Step 2: Configure

Save your API key to the config file:

mkdir -p ~/.clawdbot/skills/rips
cat > ~/.clawdbot/skills/rips/config.json << 'EOF'
{
  "apiKey": "rips_agent_live_YOUR_KEY_HERE",
  "apiUrl": "https://my.rips.app"
}
EOF

Step 3: Wait for Approval

New agents start with status: pending. An admin will review and activate your account. Check your status:

scripts/rips-me.sh

Once status: active, you can create and manage consignment deals.

Verify Setup

scripts/rips-me.sh

Core Usage

Check Agent Status

scripts/rips-me.sh

Returns your agent info including wallet address, status, and creation date.

Create a Consignment Deal

# With just the token address (metadata fetched from chain)
scripts/rips-deal-create.sh "0xTokenAddress"

# With full metadata
scripts/rips-deal-create.sh "0xTokenAddress" "TOKEN" "Token Name" 18 "https://example.com/logo.png"

Creates a new consignment deal for your token. The deal will be reviewed before tokens can be deposited.

List Your Deals

scripts/rips-deals.sh

Returns all consignment deals with on-chain contract data (balances, earnings, daily limits).

Get Deal Details

scripts/rips-deal-detail.sh "deal-uuid-here"

Returns full deal stats including on-chain balances, manager status, and token allowance.

Deposit Tokens

# Deposit 1000 tokens (18 decimals = 1000000000000000000000)
scripts/rips-deal-deposit.sh "deal-uuid" "1000000000000000000000"

Returns prepared transactions to sign and broadcast in order: 1. addManager (first time only) — authorizes your wallet on the contract 2. approve (if needed) — ERC20 token approval 3. deposit — the actual deposit call

Withdraw Tokens or Earnings

# Withdraw deposited tokens
scripts/rips-deal-withdraw.sh "deal-uuid" tokens "500000000000000000000"

# Withdraw USDC earnings
scripts/rips-deal-withdraw.sh "deal-uuid" earnings

Update Deal Preferences

# Toggle auto-withdraw
scripts/rips-deal-update.sh "deal-uuid" --auto-withdraw true

# Pause deal (prevents new purchases)
scripts/rips-deal-update.sh "deal-uuid" --pause

# Resume deal
scripts/rips-deal-update.sh "deal-uuid" --resume

# Set daily purchase limit (raw token units, 0 = unlimited)
scripts/rips-deal-update.sh "deal-uuid" --daily-limit "5000000000000000000"

Staking RIPS

Stake RIPS tokens to earn USDC rewards. Staking is a direct on-chain interaction — no API key required, just a wallet on Base.

Contracts

Network: Base (chain ID 8453)

Step 1: Acquire RIPS

Swap USDC or ETH for RIPS on any Base DEX (Uniswap V3, Aerodrome, etc).

Step 2: Approve Staker V2

Call approve on the RIPS token contract (0xc1aDDAe61Bc74a14971BFA48A0B7141AdeD4fB07):

approve(
  spender: 0xB6d7B6F1c4Ad64d75fc8c63e56188b6e3eF0c004,  // Staker V2
  amount:  <amount in wei, or type(uint256).max>
)

Step 3: Stake + Join Rewards Pool (single tx)

Call stake on Staker V2 (0xB6d7B6F1c4Ad64d75fc8c63e56188b6e3eF0c004):

stake(
  user:        <your wallet address>,
  token:       0xc1aDDAe61Bc74a14971BFA48A0B7141AdeD4fB07,  // RIPS
  quantity:    <amount in wei>,
  customize:   true,
  customPools: [0xb0D256824ACd2EE1cbC03e97C47A7B5fec9Fe5f3]  // Rewards Pool
)

Setting customize: true with the Rewards Pool address auto-joins the USDC rewards pool in the same transaction.

Step 4: Claim USDC Rewards (periodically)

Call claimRewards on Staker V2:

claimRewards(
  user:  <your wallet address>,
  token: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913  // USDC
)

Read: Check Staked Balance

Call getStake on Staker V2 — returns amount in wei (18 decimals):

getStake(user: <address>, token: 0xc1aDDAe61Bc74a14971BFA48A0B7141AdeD4fB07)

Read: Check Claimable Rewards

Call getUnpaidRewards on the Rewards Pool (0xb0D256824ACd2EE1cbC03e97C47A7B5fec9Fe5f3) — returns USDC amount (6 decimals):

getUnpaidRewards(user: <address>)

Reference: references/staking.md

Pack Designs

Browse base designs, preview your logo composited on them, and generate the 3 pack assets needed for boosted packs.

Browse Available Designs

scripts/rips-pack-designs.sh

Returns all active base designs with IDs, names, descriptions, and preview image URLs.

Preview Your Logo on a Design

scripts/rips-pack-preview.sh "foil-1" "https://example.com/logo.png" "3 COINS"

Returns a base64 data URL of the composited full pack image. To save as a file:

scripts/rips-pack-preview.sh "foil-1" "https://example.com/logo.png" | jq -r '.preview' | sed 's/data:image\/png;base64,//' | base64 -d > preview.png

Generate Final Pack Assets

scripts/rips-pack-generate.sh "foil-1" "https://example.com/logo.png" "3 COINS" "my-token-pack"

Generates all 3 asset variants (full, top, bottom), uploads to IPFS, and returns CDN URLs. Save these URLs — you'll need them when creating a boosted pack.

Reference: references/pack-designs.md

Coin Data & Card Previews

Access data about your coins on the platform, generate card preview images for marketing, and view platform statistics.

List Your Coins

scripts/rips-coins.sh

Returns all coins from your active consignment deals with market metadata (price, market cap, volume, etc).

Get Coin Details & Statistics

scripts/rips-coin-detail.sh "0xTokenAddress"

Returns full coin metadata plus platform stats: how many packs featured your coin, total cards distributed, unique users reached, and legendary cards.

Generate Card Preview

# Standard card
scripts/rips-coin-card.sh "0xTokenAddress"

# Legendary card
scripts/rips-coin-card.sh "0xTokenAddress" legendary

Returns a base64 PNG data URL of a card preview image. To save as a file:

scripts/rips-coin-card.sh "0xTokenAddress" | jq -r '.preview' | sed 's/data:image\/png;base64,//' | base64 -d > card.png

Card types:

• Standard — Silver/gray gradient card with coin logo, market cap, and 24h volume
• Legendary — Gold gradient card with "LEGENDARY" badge

Reference: references/coin-data.md

Capabilities Overview

Agent Onboarding (Phase 1)

• Self-Registration: Register with wallet signature
• Status Check: View agent status and info
• API Key Management: Secure key generation

Reference: references/agent-onboarding.md

Consignment Deals (Phase 2)

• Create deals for your tokens
• View deals with on-chain balances and earnings
• Deposit tokens with multi-step transaction preparation
• Withdraw tokens or accumulated USDC earnings
• Manage deals — pause/resume, set daily limits, toggle auto-withdraw

Reference: references/consignment-deals.md

RIPS Staking

• Stake RIPS tokens to earn USDC rewards
• Claim rewards periodically
• Check balances — staked amount and claimable USDC
• Direct on-chain interaction (no API key needed)

Reference: references/staking.md

Pack Designs (Phase 3a)

• Browse base designs with descriptions and preview images
• Preview custom pack art — composite your logo + coin text on a base design
• Generate pack assets — create all 3 variants (full, top, bottom) and upload to IPFS
• Returned CDN URLs are used when creating boosted packs

Reference: references/pack-designs.md

Coin Data & Card Previews

• List coins from your consignment deals with market metadata
• View statistics — packs, cards distributed, unique users, legendary cards
• Generate card previews — standard and legendary PNG images for marketing

Reference: references/coin-data.md

Sponsorships (Phase 3b - Coming Soon)

• Create sponsored free packs with banner ads
• Create boosted packs with subsidies using generated pack assets
• Track impressions and clicks
• Monitor campaign performance

API Endpoints

Onboarding

Deals

Pack Designs

Coin Data & Card Previews

Transaction Preparation

The deposit, withdraw, and on-chain preference endpoints return prepared transaction calldata rather than executing transactions directly. Your agent signs and broadcasts these transactions using its own wallet.

Response format:

{
  "transactions": [
    {
      "step": 1,
      "description": "Approve token transfer to the ConsignmentManager contract",
      "to": "0x...",
      "data": "0x...",
      "value": "0"
    }
  ]
}

Execute transactions in step order. Each to/data/value triplet is a standard Ethereum transaction. When multiple transactions are returned, wait for at least 2 block confirmations before sending the next transaction. Later steps often depend on state changes from earlier steps (e.g., setting a beneficiary before withdrawing earnings).

Best Practices

Security

1. Never share your API key 2. Store keys securely (environment variables or encrypted config) 3. Your wallet controls your agent - keep private keys safe 4. Start with test amounts when depositing

Token Management

1. Ensure your token has sufficient liquidity before listing 2. Check token acceptance status before large deposits 3. Monitor deal performance regularly 4. Set appropriate payout thresholds

Error Handling

Common issues and fixes:

• 401 Unauthorized → Check API key is correct and agent is active
• 403 Forbidden → You don't own this deal, or agent status is pending/suspended
• 404 Not Found → Resource doesn't exist
• 409 Conflict → Deal already exists for this token
• 503 Service Unavailable → Contract not configured (on-chain features unavailable)

Prompt Examples

Onboarding

• "Register my wallet 0x... as an agent on Rips"
• "What's my agent status?"
• "Show my agent info"

Deal Management

• "Create a consignment deal for my token at 0x..."
• "List my active deals"
• "Show details for deal abc-123"
• "Deposit 1000 tokens to my deal"
• "Withdraw my USDC earnings from deal abc-123"
• "Pause my deal"
• "Set a daily limit of 5000 tokens on my deal"

Staking

• "Stake 10 million RIPS"
• "How much RIPS do I have staked?"
• "Check my claimable USDC rewards"
• "Claim my staking rewards"

Pack Designs

• "Show me the available pack base designs"
• "Preview my logo on the purple foil design"
• "Generate pack assets with foil-1 design and my token logo"
• "Which base design would work best for a gaming token?"

Coin Data & Marketing

• "List my coins on Rips"
• "Show me the stats for my token at 0x..."
• "Generate a card preview for my token"
• "Create a legendary card image for my coin"
• "How many packs has my token been in?"

Sponsorships (Coming Soon)

• "Create a sponsored free pack campaign"
• "Set up a boosted pack with 40% subsidy"
• "Show my campaign stats"

Rips Skills

OpenClaw skills for interacting with the Rips trading card platform.

Installation

Add to your OpenClaw skills directory:

git clone https://github.com/creativelayer/rips-skills.git ~/.clawdbot/skills/rips

Or add as a skill reference in your agent configuration.

Available Skills

rips

AI-powered token consignment for the Rips trading card platform.

Capabilities:

• Agent self-registration via wallet signature
• Create consignment deals for your tokens
• List and manage active deals
• Deposit/withdraw tokens
• Stake RIPS tokens to earn USDC rewards
• (Coming soon) Sponsored packs and campaigns

See SKILL.md for full documentation.

Quick Start

# 1. Get a nonce to sign
./scripts/rips-nonce.sh "0xYourWalletAddress"

# 2. Sign the message with your wallet, then register
./scripts/rips-register.sh "0xYourWallet" "0xSignature" "nonce-uuid"

# 3. Save your API key to config (shown only once!)
mkdir -p ~/.clawdbot/skills/rips
echo '{"apiKey": "rips_agent_live_xxx", "apiUrl": "https://my.rips.app"}' > ~/.clawdbot/skills/rips/config.json

# 4. Check your status
./scripts/rips-me.sh

# 5. Create a deal (once approved)
./scripts/rips-deal-create.sh "0xTokenAddress" "TOKEN" "Token Name"

API Documentation

• Agent Onboarding - Registration and authentication
• Consignment Deals - Deal management
• Staking - Stake RIPS for USDC rewards

Requirements

• curl - HTTP client
• jq - JSON processor
• An Ethereum wallet with signing capability

Links

• Rips Platform
• Token Manager
• OpenClaw

License

MIT

Agent Onboarding

This document details the agent registration and authentication process for the Rips platform.

Overview

AI agents can self-register on the Rips platform using wallet signature verification. This proves ownership of an Ethereum wallet, which becomes the agent's identity.

Registration Flow

1. Request nonce      → GET /api/agent/nonce?address=0x...
2. Sign message       → Agent signs with wallet private key
3. Submit signature   → POST /api/agent/register
4. Receive API key    → Shown ONCE, must be saved
5. Admin approval     → Status: pending → active
6. Use API            → Bearer token authentication

Endpoints

GET /api/agent/nonce

Request a nonce for signing. The nonce is used to prevent replay attacks.

Query Parameters:

• address (required): Your Ethereum wallet address (0x...)

Response:

{
  "nonce": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Rips Agent Registration\n\nDomain: my.rips.app\nAddress: 0x1234...\nNonce: 550e8400-e29b-41d4-a716-446655440000\nIssued At: 2026-02-09T12:00:00Z\nExpires At: 2026-02-09T12:05:00Z\n\nI am registering as an AI agent on the Rips platform.",
  "expiresAt": "2026-02-09T12:05:00Z"
}

Notes:

• Nonces expire after 5 minutes
• Each nonce can only be used once
• The message field contains the exact string that must be signed

POST /api/agent/register

Complete registration with a signed message.

Request Body:

{
  "address": "0x1234567890abcdef...",
  "signature": "0x...",
  "nonce": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Trading Bot",
  "description": "Automated token consignment agent",
  "contactEmail": "agent@example.com"
}

Response (201 Created):

{
  "agentId": "agent_abc123...",
  "apiKey": "rips_agent_live_abc123def456...",
  "status": "pending",
  "message": "Save your API key - it will not be shown again."
}

Errors:

• 400 Bad Request - Missing required fields or invalid signature
• 409 Conflict - Agent already exists for this wallet

GET /api/agent/me

Get current agent information. Requires authentication.

Headers:

Authorization: Bearer rips_agent_live_xxx

Response:

{
  "agentId": "agent_abc123...",
  "walletAddress": "0x1234...",
  "name": "My Trading Bot",
  "description": "Automated token consignment agent",
  "status": "active",
  "createdAt": "2026-02-09T12:00:00Z"
}

Status Values:

• pending - Awaiting admin approval
• active - Can use all API features
• suspended - Temporarily disabled
• revoked - Permanently disabled

Signature Format

The Rips API uses EIP-191 personal_sign for message signing. This is the standard eth_sign / personal_sign method supported by all Ethereum wallets.

Signing with viem

import { privateKeyToAccount } from 'viem/accounts'

const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY')
const signature = await account.signMessage({
  message: messageFromNonceEndpoint
})

Signing with ethers.js

import { Wallet } from 'ethers'

const wallet = new Wallet('0xYOUR_PRIVATE_KEY')
const signature = await wallet.signMessage(messageFromNonceEndpoint)

Signing with web3.js

const signature = await web3.eth.personal.sign(
  messageFromNonceEndpoint,
  walletAddress,
  '' // password (empty for most wallets)
)

Authentication

After registration, use your API key for all authenticated requests:

curl -H "Authorization: Bearer rips_agent_live_xxx" \
  https://my.rips.app/api/agent/me

Security

• API keys are shown only once at registration - save them immediately
• Keys are hashed with bcrypt - we cannot recover lost keys
• Lost key? Contact support to regenerate (future: /api/agent/regenerate-key)
• Compromised key? Contact support immediately to revoke

Rate Limits

Coin Data & Card Previews

This document details how AI agents can access data about their coins on the Rips platform, including card preview images for marketing.

Overview

Agents with consignment deals can:

• List all their coins and market metadata
• Get detailed statistics on how their coins perform on the platform
• Generate card preview images (standard and legendary) for marketing use

Endpoints

All coin endpoints require authentication:

Authorization: Bearer rips_agent_live_xxx

GET /api/agent/coins — List Your Coins

Returns all coins from your active consignment deals with market metadata.

Response:

{
  "coins": [
    {
      "tokenAddress": "0x1234...abcd",
      "symbol": "MTK",
      "name": "My Token",
      "image": "https://d2geem9d3khxko.cloudfront.net/ipfs/Qm...",
      "decimals": 18,
      "currentPrice": 0.00042,
      "marketCap": 420000,
      "volume24h": 52000,
      "priceChange1h": 2.5,
      "priceChange6h": -1.3,
      "priceChange24h": 8.7,
      "holders": 1250,
      "liquidity": 85000,
      "website": "https://mytoken.xyz",
      "twitterHandle": "mytoken",
      "dealId": "uuid",
      "dealStatus": "active"
    }
  ]
}

Errors:

• 401 — Invalid or missing API key

---

GET /api/agent/coins/:address — Coin Details & Statistics

Returns detailed coin metadata and platform statistics. You must have an active deal for this coin.

Path Parameters:

Response:

{
  "coin": {
    "tokenAddress": "0x1234...abcd",
    "symbol": "MTK",
    "name": "My Token",
    "image": "https://d2geem9d3khxko.cloudfront.net/ipfs/Qm...",
    "decimals": 18,
    "currentPrice": 0.00042,
    "marketCap": 420000,
    "volume24h": 52000,
    "priceChange1h": 2.5,
    "priceChange6h": -1.3,
    "priceChange24h": 8.7,
    "holders": 1250,
    "liquidity": 85000,
    "website": "https://mytoken.xyz",
    "twitterHandle": "mytoken"
  },
  "stats": {
    "totalPacks": 156,
    "totalCards": 892,
    "uniqueUsers": 234,
    "legendaryCards": 3
  }
}

Stats Fields:

Errors:

• 401 — Invalid or missing API key
• 404 — No active deal for this token, or token not found

---

GET /api/agent/coins/:address/card-preview — Generate Card Preview

Generates a card preview image for your coin in standard or legendary style. Returns a base64 PNG data URL that you can decode and use for marketing materials, social media posts, etc.

Path Parameters:

Query Parameters:

Example Request:

GET /api/agent/coins/0x1234...abcd/card-preview?type=legendary
Authorization: Bearer rips_agent_live_xxx

Response:

{
  "preview": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
  "type": "legendary",
  "tokenAddress": "0x1234...abcd",
  "symbol": "MTK"
}

Card Styles:

• Standard — Silver/gray gradient card showing coin logo, market cap, and 24h volume
• Legendary — Gold gradient card with "LEGENDARY" badge

Using the preview image: The preview field contains a data URL. To save it as a file:

import base64
data = response["preview"].split(",")[1]
with open("card.png", "wb") as f:
    f.write(base64.b64decode(data))

Errors:

• 401 — Invalid or missing API key
• 404 — No active deal for this token, or token not found

Use Cases

Marketing & Social Media

Generate card preview images to share on Twitter, Discord, or Telegram to promote your token's presence on the Rips platform.

Portfolio Dashboards

Use the coin details and statistics endpoints to display how your token is performing — how many users hold your cards, how many packs featured your coin, etc.

Performance Tracking

Monitor priceChange1h/6h/24h, volume24h, and platform stats over time to understand the impact of being on the Rips platform.

Consignment Deals

This document details how AI agents can create and manage consignment deals on the Rips platform.

Overview

Consignment deals allow token projects to have their tokens included in Rips trading card packs. When users purchase packs containing your tokens, you earn revenue.

Deal Lifecycle

1. Create Deal    → POST /api/deals (status: pending)
2. Admin Review   → Manual approval process
3. Activation     → Status changes to active
4. Deposit Tokens → POST /api/agent/deals/:id/deposit → sign & broadcast
5. Earn Revenue   → Tokens purchased for packs, USDC accumulates
6. Withdraw       → POST /api/agent/deals/:id/withdraw → sign & broadcast

Endpoints

All deal management endpoints require authentication:

Authorization: Bearer rips_agent_live_xxx

POST /api/deals — Create a Deal

Request Body:

{
  "tokenAddress": "0x1234567890abcdef...",
  "tokenName": "My Token",
  "tokenSymbol": "MTK",
  "tokenDecimals": 18,
  "tokenLogo": "https://example.com/logo.png",
  "minPayoutUsd": 10.0
}

Response (201 Created):

{
  "deal": {
    "id": "uuid",
    "supplierAddress": "0x...",
    "tokenAddress": "0x...",
    "tokenSymbol": "MTK",
    "status": "pending",
    "createdAt": "2026-02-09T12:00:00Z"
  }
}

Errors:

• 400 — Missing tokenAddress
• 401 — Invalid or missing API key
• 409 — Deal already exists for this token

GET /api/agent/deals — List Deals

Returns all your deals enriched with on-chain contract data.

Response:

{
  "deals": [
    {
      "id": "uuid",
      "tokenAddress": "0x...",
      "tokenSymbol": "MTK",
      "status": "active",
      "deposited": 1000.5,
      "purchased": 200.0,
      "availableBalance": 800.5,
      "totalUsdPaid": 150.00,
      "pendingEarnings": 25.00,
      "availableFormatted": "800.5",
      "availableUsd": "$400.25",
      "dailyLimit": 100,
      "dailyRemaining": 75,
      "createdAt": "2026-02-09T12:00:00Z"
    }
  ]
}

GET /api/agent/deals/:id — Deal Details

Returns a single deal with full stats and your on-chain context.

Response:

{
  "deal": {
    "id": "uuid",
    "tokenSymbol": "MTK",
    "status": "active",
    "deposited": 1000.5,
    "availableBalance": 800.5,
    "pendingEarnings": 25.00
  },
  "onChainStatus": {
    "isManager": true,
    "tokenAllowance": "1000000000000000000",
    "contractConfigured": true
  }
}

POST /api/agent/deals/:id/deposit — Prepare Deposit

Prepares transaction calldata for depositing tokens. May return multiple transactions.

Request:

{ "amount": "1000000000000000000" }

Amount is in raw token units (e.g., 1000000000000000000 = 1 token with 18 decimals).

Response:

{
  "dealId": "uuid",
  "tokenAddress": "0x...",
  "tokenSymbol": "MTK",
  "amount": "1000000000000000000",
  "transactions": [
    {
      "step": 1,
      "description": "Add your wallet as a manager for this deal",
      "to": "0x...",
      "data": "0x...",
      "value": "0"
    },
    {
      "step": 2,
      "description": "Approve token transfer to the ConsignmentManager contract",
      "to": "0x...",
      "data": "0x...",
      "value": "0"
    },
    {
      "step": 3,
      "description": "Deposit tokens into the consignment deal",
      "to": "0x...",
      "data": "0x...",
      "value": "0"
    }
  ]
}

Steps 1 and 2 are only included when needed (first deposit, or insufficient allowance).

Errors:

• 400 — Deal not active, invalid amount
• 403 — You don't own this deal
• 503 — Contract not configured

POST /api/agent/deals/:id/withdraw — Prepare Withdrawal

Prepares transaction calldata for withdrawing tokens or earnings.

Request (withdraw tokens):

{ "type": "tokens", "amount": "500000000000000000" }

Request (withdraw earnings):

{ "type": "earnings" }

Response:

{
  "dealId": "uuid",
  "type": "tokens",
  "amount": "500000000000000000",
  "transactions": [
    {
      "step": 1,
      "description": "Withdraw tokens from the consignment deal",
      "to": "0x...",
      "data": "0x...",
      "value": "0"
    }
  ]
}

Errors:

• 400 — Insufficient balance, no pending earnings, invalid type
• 403 — You don't own this deal

PATCH /api/agent/deals/:id — Update Preferences

Updates deal settings. Neo4j-side changes apply immediately; on-chain changes return transaction calldata.

Request:

{
  "autoWithdraw": true,
  "pause": true,
  "dailyLimit": "5000000000000000000"
}

Response:

{
  "deal": { "...deal stats..." },
  "transactions": [
    {
      "step": 1,
      "description": "Pause the consignment deal",
      "to": "0x...",
      "data": "0x...",
      "value": "0"
    }
  ]
}

Deal Status Values

Transaction Execution

On-chain operations (deposit, withdraw, pause, resume, dailyLimit) return prepared transaction calldata. Your agent must:

1. Receive the transactions array from the API 2. Execute each transaction in step order 3. Sign with your wallet private key 4. Broadcast on Base network 5. Wait for at least 2 block confirmations before proceeding to the next step — later steps depend on state changes from earlier ones

Each transaction provides { to, data, value } — standard Ethereum transaction fields.

Best Practices

Token Requirements

For best results, your token should have:

• Sufficient liquidity on Base (DEX pools)
• Reasonable market cap ($100K+ recommended)
• Active trading volume
• Clear token metadata (name, symbol, logo)

Deal Management

1. Start small — Begin with a test deposit to verify everything works 2. Monitor performance — Check deal details regularly for earnings 3. Keep tokens available — Ensure sufficient balance for pack generation 4. Set realistic limits — Daily limits help manage exposure 5. Use auto-withdraw — Toggle on for automatic earnings collection

Rate Limits

Pack Designs

This document details how AI agents can browse base designs, preview custom pack art, and generate final pack assets for boosted packs on the Rips platform.

Overview

Pack designs define the visual appearance of trading card packs. Each base design is a foil template with a distinct visual style. Agents composite their token logo and coin text onto a chosen base design to create custom pack art for boosted packs.

The 3 generated assets (full, top, bottom) are used by the rip animation — the full image is the sealed pack, top stays fixed while the bottom slides down to reveal cards.

Design Workflow

1. Browse Designs  → GET /api/agent/pack-designs (list available base designs)
2. Preview         → POST /api/agent/pack-designs/preview (see logo composited on design)
3. Generate Assets → POST /api/agent/pack-designs/generate (create & upload final assets)
4. Use in Pack     → Supply asset URLs when creating a boosted pack (coming soon)

Endpoints

All pack design endpoints require authentication:

Authorization: Bearer rips_agent_live_xxx

GET /api/agent/pack-designs — List Base Designs

Returns all active base designs with descriptions and preview images.

Response:

{
  "designs": [
    {
      "id": "foil-1",
      "name": "Foil 1",
      "description": "A sleek metallic silver foil with holographic rainbow light bands...",
      "previewImageUrl": "https://d2geem9d3khxko.cloudfront.net/ipfs/..."
    }
  ]
}

POST /api/agent/pack-designs/preview — Generate Preview

Composites your logo and coin text onto a base design and returns a base64 preview image. Only generates the full variant for speed.

Request:

{
  "baseDesignId": "foil-1",
  "logoUrl": "https://example.com/logo.png",
  "coinText": "3 COINS"
}

Response:

{
  "preview": "data:image/png;base64,iVBORw0KGgo..."
}

The preview is a base64-encoded PNG data URL of the full pack image (765x1295px).

Errors:

• 400 — Missing baseDesignId or logoUrl
• 401 — Invalid or missing API key
• 404 — Base design not found or inactive
• 422 — Logo URL unreachable or invalid image

POST /api/agent/pack-designs/generate — Generate & Upload Assets

Composites logo and coin text onto a base design, generates all 3 pack asset variants, uploads them to IPFS, and returns CDN URLs.

Request:

{
  "baseDesignId": "foil-1",
  "logoUrl": "https://example.com/logo.png",
  "coinText": "3 COINS",
  "packName": "my-token-pack"
}

Response:

{
  "images": {
    "fullImage": "https://d2geem9d3khxko.cloudfront.net/ipfs/bafybei...",
    "topImage": "https://d2geem9d3khxko.cloudfront.net/ipfs/bafybei...",
    "bottomImage": "https://d2geem9d3khxko.cloudfront.net/ipfs/bafybei..."
  }
}

Errors:

• 400 — Missing baseDesignId or logoUrl
• 401 — Invalid or missing API key
• 404 — Base design not found or inactive
• 422 — Logo URL unreachable or invalid image
• 503 — IPFS upload service not configured

Logo Guidelines

The logo is composited into a 600x400px area on the pack. Logos larger than this are aspect-fit (scaled down proportionally to fit within the bounds). Smaller logos are centered without upscaling.

• Format: PNG with transparent background (required for non-rectangular logos so the foil design shows through)
• Max placement size: 600w x 400h pixels — logos are aspect-fit within this area
• Recommended source size: At least 600x400px for crisp rendering
• Content: Clear, high-contrast artwork that reads well on metallic/patterned backgrounds
• Background: Transparent PNG strongly recommended. Square or rectangular logos with solid backgrounds will work but may look boxy against the foil

Choosing a Base Design

Use the description field to match your token's brand:

• Metallic/tech tokens: Look for foil designs with holographic or chrome effects
• Gaming tokens: Lightning or energy-themed designs
• Premium/luxury tokens: Purple or gold-toned designs
• General purpose: Clean foil designs work well with any logo

Browse all designs first, then preview your logo on 2-3 candidates before generating final assets.

Best Practices

1. Preview before generating — Preview is fast and free; generation uploads permanently to IPFS 2. Use transparent PNGs — Logos with solid backgrounds won't blend well with foil designs 3. Check coin text — Match the coin text to your actual pack value (e.g., "3 COINS", "5 COINS") 4. Save the CDN URLs — You'll need all 3 asset URLs when creating your boosted pack

Staking RIPS

Stake RIPS tokens on Base to earn USDC rewards from the Rips platform fee pool.

Contracts

Network: Base (chain ID 8453)

Decimals matter: RIPS uses 18 decimals (1 RIPS = 1000000000000000000 wei). USDC uses 6 decimals (1 USDC = 1000000). Don't mix these up when formatting amounts for display or when parsing return values.

How It Works

1. You stake RIPS tokens into the Staker V2 contract 2. You join the Rewards Pool to start earning 3. Platform swap fees are distributed as USDC to the Rewards Pool 4. Rewards accumulate proportionally based on your staked amount 5. You claim USDC rewards whenever you want

Transactions

1. Approve RIPS spending

Standard ERC-20 approval on the RIPS token contract.

Contract: 0xc1aDDAe61Bc74a14971BFA48A0B7141AdeD4fB07 (RIPS Token)

function approve(address spender, uint256 amount) returns (bool)

2. Stake + Join Rewards Pool (single transaction)

Key UX detail: By passing customize: true with the Rewards Pool address in customPools, the stake() call both stakes your RIPS and joins the USDC rewards pool in a single transaction. Without this, you'd need a separate joinPools() call, and you won't earn rewards until you do.

Contract: 0xB6d7B6F1c4Ad64d75fc8c63e56188b6e3eF0c004 (Staker V2)

function stake(address user, address token, uint256 quantity, bool customize, address[] customPools)

<details> <summary>ABI</summary>

{
  "inputs": [
    { "internalType": "address", "name": "user", "type": "address" },
    { "internalType": "address", "name": "token", "type": "address" },
    { "internalType": "uint256", "name": "quantity", "type": "uint256" },
    { "internalType": "bool", "name": "customize", "type": "bool" },
    { "internalType": "address[]", "name": "customPools", "type": "address[]" }
  ],
  "name": "stake",
  "outputs": [],
  "stateMutability": "nonpayable",
  "type": "function"
}

</details>

3. Claim USDC Rewards

Claims all accumulated USDC rewards.

Contract: 0xB6d7B6F1c4Ad64d75fc8c63e56188b6e3eF0c004 (Staker V2)

function claimRewards(address user, address token)

<details> <summary>ABI</summary>

{
  "inputs": [
    { "internalType": "address", "name": "user", "type": "address" },
    { "internalType": "address", "name": "token", "type": "address" }
  ],
  "name": "claimRewards",
  "outputs": [],
  "stateMutability": "nonpayable",
  "type": "function"
}

</details>

4. Unstake (optional)

Returns staked RIPS tokens to your wallet.

Contract: 0xB6d7B6F1c4Ad64d75fc8c63e56188b6e3eF0c004 (Staker V2)

function unstake(address user, address token, uint256 quantity)

<details> <summary>ABI</summary>

{
  "inputs": [
    { "internalType": "address", "name": "user", "type": "address" },
    { "internalType": "address", "name": "token", "type": "address" },
    { "internalType": "uint256", "name": "quantity", "type": "uint256" }
  ],
  "name": "unstake",
  "outputs": [],
  "stateMutability": "nonpayable",
  "type": "function"
}

</details>

Read Functions

Check Staked Balance

Contract: 0xB6d7B6F1c4Ad64d75fc8c63e56188b6e3eF0c004 (Staker V2)

function getStake(address user, address token) view returns (uint256)

Returns staked amount in wei (18 decimals — divide by 1e18 for human-readable RIPS amount).

<details> <summary>ABI</summary>

{
  "inputs": [
    { "internalType": "address", "name": "user", "type": "address" },
    { "internalType": "address", "name": "token", "type": "address" }
  ],
  "name": "getStake",
  "outputs": [
    { "internalType": "uint256", "name": "", "type": "uint256" }
  ],
  "stateMutability": "view",
  "type": "function"
}

</details>

Check Claimable Rewards

Contract: 0xb0D256824ACd2EE1cbC03e97C47A7B5fec9Fe5f3 (Rewards Pool)

function getUnpaidRewards(address user) view returns (uint256)

Returns claimable USDC amount (6 decimals — divide by 1e6 for human-readable USDC amount).

<details> <summary>ABI</summary>

{
  "inputs": [
    { "internalType": "address", "name": "user", "type": "address" }
  ],
  "name": "getUnpaidRewards",
  "outputs": [
    { "internalType": "uint256", "name": "", "type": "uint256" }
  ],
  "stateMutability": "view",
  "type": "function"
}

</details>

Check if Joined Rewards Pool

Contract: 0xB6d7B6F1c4Ad64d75fc8c63e56188b6e3eF0c004 (Staker V2)

function hasJoinedPool(address user, address token, address pool) view returns (bool)

Returns true if the user is earning rewards.

Additional Operations

Join Rewards Pool (if not done during stake)

If you staked with customize: false, you need to join the pool separately.

Contract: 0xB6d7B6F1c4Ad64d75fc8c63e56188b6e3eF0c004 (Staker V2)

function joinPools(address user, address[] pools)

Leave Rewards Pool

Stop earning rewards while keeping tokens staked.

Contract: 0xB6d7B6F1c4Ad64d75fc8c63e56188b6e3eF0c004 (Staker V2)

function leavePools(address user, address[] pools, bool useGasCap)