Welcome

Ethereum ↔ Stacks Cross-Chain Bridge

The API enables seamless, gasless transfer of USDC between Ethereum Sepolia and Stacks testnet using Circle’s Cross-Chain Transfer Protocol (CCTP). The bridge handles all transaction complexity automatically - simply initiate a transfer and deposit funds to the provided address.

This API documentation is built using OpenAPI specification and provides interactive endpoint testing through Swagger UI.

Base URL: https://stacks.aboki.xyz

API Specification

🌉 Cross-Chain Bridge Endpoints

Explore the complete OpenAPI specification for all bridge operations, including request/response schemas, authentication requirements, and interactive endpoint testing.

View OpenAPI Specification →

The specification includes:

• Bridge operations (Ethereum ↔ Stacks)
• Wallet information endpoints
• Health check and monitoring
• Detailed request/response examples
• Interactive API testing interface

Authentication

This API currently operates without authentication for testnet development purposes. All endpoints are publicly accessible to facilitate testing and integration.

Future Authentication

When mainnet launches, the API will implement Bearer token authentication for security.

Authentication will be required for:

• All bridge operations
• Wallet balance queries
• Session management

API keys will be provided through a developer dashboard upon mainnet release.

Current Testnet Access

For now, simply make HTTP requests to any endpoint without authentication headers:

# No authentication required on testnet
curl -X POST https://stacks.aboki.xyz/api/bridge/eth-to-stacks \
  -H "Content-Type: application/json" \
  -d '{"amountUSDC": "100", "stacksRecipient": "ST1..."}'

Network Status

Currently Available: Testnet Only
Coming Soon: Mainnet Support

• Ethereum: Sepolia Testnet → Mainnet deployment planned
• Stacks: Stacks Testnet → Mainnet deployment planned
• Tokens: Test USDC/USDCx → Real USDC/USDCx on mainnet launch

This API currently operates on testnets only. All tokens are for testing purposes and have no real value. Mainnet support is coming soon - stay tuned for updates.

Why Use This API?

Zero Gas Fees

CDP sponsors all Ethereum transaction costs

Fully Automated

Deposits trigger automatic bridge execution

Production-Ready

Built on Circle’s CCTP standard

Developer Friendly

RESTful API with comprehensive Swagger documentation

Key Features

⛽ Gasless Transactions

All Ethereum gas fees are sponsored by Coinbase Developer Platform (CDP) - users pay $0 for transaction execution.

🤖 Automated Bridge Execution

• Ethereum → Stacks: Auto-detects deposits every 15 seconds
• Stacks → Ethereum: Auto-detects deposits every 10 seconds
• No manual transaction triggering required

📊 Real-time Status Tracking

Monitor your bridge transactions at every step:

• Wallet creation
• Deposit confirmation
• Approval & execution
• Minting/burning
• Completion

🏦 Smart Wallet Management

Automatic creation and management of gasless smart wallets and temporary Stacks wallets for seamless bridging.

Quick Example

Bridge USDC from Ethereum to Stacks

1. Initiate the bridge

       curl -X POST https://stacks.aboki.xyz/api/bridge/eth-to-stacks \
         -H "Content-Type: application/json" \
         -d '{
           "amountUSDC": "100",
           "stacksRecipient": "ST1HSKQ5NH4QQBV03SYCARJEN0CVB7PA7ACQ7HZM5"
         }'
   
2. Deposit USDC

   Response includes a depositAddress - send your USDC there and the bridge executes automatically.

3. Monitor status

       curl https://stacks.aboki.xyz/api/bridge/status/{sessionId}
   

The bridge handles approval, deposit to xReserve, and USDCx minting automatically!

How It Works

Ethereum → Stacks

USDC to USDCx Bridge Flow

1. Wallet Creation: API creates a gasless smart wallet via CDP
2. User Deposits: You send USDC to the wallet address
3. Auto-Approval: Bridge approves USDC for xReserve contract
4. Deposit to xReserve: USDC deposited to Circle’s CCTP contract
5. Minting: USDCx is minted on Stacks to your recipient address

Total Time: ~15-20 minutes
User Gas Cost: $0 (CDP sponsored)

Stacks → Ethereum

USDCx to USDC Bridge Flow

1. Wallet Generation: API creates a temporary Stacks wallet
2. User Deposits: You send USDCx to the wallet address
3. Gas Transfer: Bridge automatically sends STX for transaction fees
4. USDCx Burn: Bridge burns USDCx on Stacks
5. USDC Release: USDC is released to your Ethereum address

Total Time: ~15-20 minutes
User Gas Cost: Covered by bridge (admin sends STX)

Important Concepts

Smart Wallet

A gasless Ethereum wallet created via Coinbase Developer Platform (CDP) that sponsors all transaction fees. Users never pay for gas on Ethereum transactions.

Bridge Session

A tracked cross-chain transfer with a unique session ID. Each session monitors the entire lifecycle from deposit to completion.

xReserve Contract

Circle’s Cross-Chain Transfer Protocol (CCTP) contract that handles cross-chain USDC transfers between supported chains.

USDCx

The Stacks-native representation of USDC. Fully backed 1:1 by USDC through Circle’s CCTP protocol.

Auto-execution

Deposits are automatically detected every 10-15 seconds. Once sufficient funds are detected, the bridge executes all remaining steps without user intervention.

Prerequisites

Ethereum → Stacks

Requirements

• USDC on Ethereum Sepolia testnet
• A Stacks wallet address to receive USDCx
• Minimum amount: 0.01 USDC (or more, depending on your needs)

Stacks → Ethereum

Requirements

• USDCx on Stacks testnet
• An Ethereum wallet address to receive USDC
• Minimum amount: 0.01 USDCx

Get Testnet Tokens

Sepolia ETH

Get test ETH for Sepolia

Sepolia USDC

Get test USDC from Circle

Stacks STX

Get test STX tokens

Expected Timings

Operation	Duration
Ethereum → Stacks	15-20 minutes total
Stacks → Ethereum	15-20 minutes total
Deposit Detection	Every 10-15 seconds
Transaction Confirmation	Varies by network (2-5 minutes)
CCTP Message Processing	10-15 minutes

Times may vary based on network congestion and blockchain confirmation speeds.

API Endpoints Overview

Endpoint	Method	Purpose
/api/bridge/eth-to-stacks	POST	Initiate Ethereum → Stacks bridge
/api/bridge/initiate-stacks-to-eth	POST	Initiate Stacks → Ethereum bridge
/api/bridge/status/:sessionId	GET	Check bridge session status
/api/wallet/ethereum	GET	View Ethereum wallet balance
/api/wallet/stacks	GET	View Stacks wallet balance
/api/health	GET	API health check

Visit the API Reference section to test these endpoints interactively!

Getting Started

1. Set up your environment

   Ensure you have access to https://stacks.aboki.xyz or are running the API locally

2. Get testnet tokens

   Acquire USDC or USDCx from the faucets above

3. Choose your direction

   Decide whether to bridge Ethereum→Stacks or Stacks→Ethereum

4. Initiate a bridge

   Make a POST request to the appropriate endpoint

5. Deposit funds

   Send tokens to the provided deposit address

6. Monitor progress

   Track your transaction using the status endpoint

Resources

Interactive API Docs

Swagger UI for testing endpoints

Circle CCTP Docs

Learn about Cross-Chain Transfer Protocol

CDP Smart Wallet Guide

Gasless wallet documentation

Stacks Documentation

Learn about Stacks blockchain