How to Create Your First Batch

By X402 Team | Last Updated: February 2026

Goal

Create a properly structured X402 batch from planning through completion, following best practices for organization and quality.

What You'll Achieve

  • Well-planned batch with clear scope
  • Organized batch INDEX with all items listed
  • Quality templates selected and customized
  • First content item created and reviewed
  • Batch properly tracked in main INDEX

Prerequisites

  • X402 repository set up (see "How to Set Up X402 in 5 Minutes")
  • Text editor installed
  • Basic understanding of markdown
  • 15-30 minutes available

Time Required

Planning: 5 minutes Setup: 5 minutes First content item: 10-20 minutes Total: 20-30 minutes

Step-by-Step Instructions

Phase 1: Planning Your Batch (5 minutes)

Step 1: Define Batch Purpose

Answer these questions:

  • What topic does this batch cover?
Example: "User authentication documentation"

  • Who is the audience?
Example: "Developers integrating our API"
  • What's the goal?
Example: "Complete authentication documentation for v2.0 launch"

Write it down: 

# Create planning doc (optional but recommended)
cat > batch-planning.md <<'EOF'

Batch 002 Planning



Purpose

Document all user authentication methods for API v2.0


Audience

Backend developers integrating with our API


Goal

Complete authentication docs before v2.0 launch (Dec 1)


Success Criteria


    

  • All auth methods documented
    • 

  • Code examples in 3 languages
    • 

  • Security best practices included
    • 


EOF

Step 2: List Content Items

Brainstorm everything that needs to be created:

## Content Items (brainstorm)

    

  • OAuth 2.0 authentication
    • 

  • API key authentication
    • 

  • JWT token authentication
    • 

  • Authentication best practices
    • 

  • Common authentication errors
    • 

  • Authentication FAQ

Prioritize items:

  1. Essential (must have)
  2. Important (should have)
  3. Nice-to-have (could have)

Step 3: Determine Batch Number

# Find next available batch number
ls -d batch- | sort -V | tail -1

If last batch is batch-001, next is batch-002

Phase 2: Create Batch Structure (5 minutes)

Step 4: Create Batch Folder

# Create directory for batch-002
mkdir batch-002


Verify creation

ls -d batch-

Step 5: Create Batch INDEX

cat > batch-002/INDEX.md <<'EOF'

Batch 002 — User Authentication Documentation



Status: In Progress



Content Items



    

  • [ ] OAuth 2.0 Authentication Guide
    • 

  • [ ] API Key Authentication Guide
    • 

  • [ ] JWT Token Authentication Guide
    • 

  • [ ] Authentication Best Practices
    • 

  • [ ] Common Authentication Errors
    • 




Notes

Authentication documentation for API v2.0 launch.
Target completion: November 30, 2024
Owner: [Your Name]


Resources


    

  • API v2.0 specification
    • 

  • Security team review required
    • 

  • Code examples repository
    • 


EOF

Key elements explained:

  • Title: Clear, descriptive batch name
  • Status: Always starts as "In Progress"
  • Content Items: Unchecked boxes for all planned content
  • Notes: Context, deadlines, ownership
  • Resources: (Optional) Links, dependencies, references

Step 6: Update Main INDEX

# Read current INDEX
cat INDEX.md


Add new batch entry

echo "- [ ] batch-002 — In Progress (0/5 titles)" >> INDEX.md

Or edit manually: 

## Batches



    

  • [x] batch-001 — Complete (5/5 titles)
    • 

  • [ ] batch-002 — In Progress (0/5 titles)  # Add this line

Step 7: Select/Create Template

Option A: Use existing template 

# List available templates
ls templates/



Copy template for reference

cp templates/api-doc-template.md batch-002/TEMPLATE.md

Option B: Create batch-specific template 

cat > batch-002/auth-guide-template.md <<'EOF'

[Authentication Method] — Authentication Guide



Overview

[Brief description of this authentication method]


How It Works

[Explanation of the authentication flow]


Implementation



Prerequisites

[What developers need before implementing]


Step-by-Step Setup


    

  1. [First step]
    2. 

  2. [Second step]
    3. 

  3. [Third step]
    4. 




Code Examples



cURL
bash [cURL example] 


JavaScript
javascript [JavaScript example] 


Python
python [Python example] 


Security Considerations

[Important security notes]


Troubleshooting

[Common issues and solutions]


Quality Standards


    

  • [ ] All code examples tested
    • 

  • [ ] Security review completed
    • 

  • [ ] Examples in 3+ languages
    • 

  • [ ] Ready for production
    • 


EOF

Phase 3: Create First Content Item (10-20 minutes)

Step 8: Start with Highest Priority Item

# Create first content file
touch batch-002/oauth-authentication-guide.md

Step 9: Follow Template Structure

Open batch-002/oauth-authentication-guide.md and write:

# OAuth 2.0 Authentication — Authentication Guide


Overview

OAuth 2.0 is the industry-standard protocol for authorization. Our API supports OAuth 2.0 for secure, delegated access to user resources.


How It Works



OAuth 2.0 uses access tokens instead of passwords:



    

  1. User authorizes your application
    2. 

  2. Authorization server issues access token
    3. 

  3. Your app uses token to access API
    4. 

  4. Token expires after set time period
    5. 




Flow Diagram
User → Authorization Request → Auth Server Auth Server → Access Token → Your App Your App → API Request + Token → API Server API Server → Protected Resource → Your App 


Implementation



Prerequisites


    

  • Registered application (get client ID and secret)
    • 

  • Redirect URI configured
    • 

  • HTTPS endpoint for callbacks
    • 




Step-by-Step Setup



1. Register Your Application

Visit https://api.example.com/apps/register


Required information:

    

  • Application name
    • 

  • Redirect URI
    • 

  • Application description
    • 




You'll receive:

    

  • Client ID: abc123...
    • 

  • Client Secret: xyz789... (keep secure!)
    • 




2. Request Authorization



Redirect user to authorization endpoint:
https://api.example.com/oauth/authorize? client_id=YOUR_CLIENT_ID& redirect_uri=YOUR_REDIRECT_URI& response_type=code& scope=read,write 


3. Handle Callback



User approves and is redirected back:
https://yourapp.com/callback?code=AUTH_CODE 


4. Exchange Code for Token



POST to token endpoint:
http POST /oauth/token Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID& client_secret=YOUR_CLIENT_SECRET& code=AUTH_CODE& grant_type=authorization_code& redirect_uri=YOUR_REDIRECT_URI 


Response:
json { "access_token": "eyJhbGc...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "def456..." } 


5. Use Access Token



Include in API requests:
http GET /api/v2/user Authorization: Bearer eyJhbGc... 


Code Examples



cURL
bash

Request authorization (open in browser)

https://api.example.com/oauth/authorize?client_id=abc123&redirect_uri=https://yourapp.com/callback&response_type=code

Exchange code for token

curl -X POST https://api.example.com/oauth/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "client_id=abc123&client_secret=xyz789&code=AUTH_CODE&grant_type=authorization_code&redirect_uri=https://yourapp.com/callback"

Use token

curl https://api.example.com/api/v2/user \ -H "Authorization: Bearer eyJhbGc..." 


JavaScript (Node.js)
javascript const axios = require('axios');

// Step 1: Build authorization URL const authUrl = https://api.example.com/oauth/authorize? + client_id=${CLIENT_ID}& + redirect_uri=${REDIRECT_URI}& + response_type=code;

// Redirect user to authUrl

// Step 2: Handle callback (Express example) app.get('/callback', async (req, res) => { const { code } = req.query;

// Step 3: Exchange code for token const tokenResponse = await axios.post('https://api.example.com/oauth/token', { client_id: CLIENT_ID, client_secret: CLIENT_SECRET, code: code, grant_type: 'authorization_code', redirect_uri: REDIRECT_URI });

const { access_token } = tokenResponse.data;

// Step 4: Use token const userResponse = await axios.get('https://api.example.com/api/v2/user', { headers: { 'Authorization': Bearer ${access_token} } });

res.json(userResponse.data); }); 



Python
python import requests

Step 1: Build authorization URL

auth_url = ( "https://api.example.com/oauth/authorize?" f"client_id={CLIENT_ID}&" f"redirect_uri={REDIRECT_URI}&" "response_type=code" )

Redirect user to auth_url

Step 2: Handle callback (Flask example)

@app.route('/callback') def callback(): code = request.args.get('code')

# Step 3: Exchange code for token token_response = requests.post('https://api.example.com/oauth/token', data={ 'client_id': CLIENT_ID, 'client_secret': CLIENT_SECRET, 'code': code, 'grant_type': 'authorization_code', 'redirect_uri': REDIRECT_URI })

access_token = token_response.json()['access_token']

# Step 4: Use token user_response = requests.get( 'https://api.example.com/api/v2/user', headers={'Authorization': f'Bearer {access_token}'} )

return user_response.json() 



Security Considerations



Critical Security Rules



    

  1. Never expose client secret
    2. 



    

  • Store in environment variables
    • 

  • Never commit to version control
    • 

  • Never include in client-side code
    • 




    

  1. Always use HTTPS
    2. 



    

  • Redirect URIs must use HTTPS
    • 

  • Token exchange must use HTTPS
    • 

  • API requests must use HTTPS
    • 




    

  1. Validate redirect URI
    2. 



    

  • Must exactly match registered URI
    • 

  • Prevents authorization code interception
    • 




    

  1. Store tokens securely
    2. 



    

  • Use secure, HTTP-only cookies
    • 

  • Never store in localStorage
    • 

  • Encrypt at rest
    • 




    

  1. Implement token refresh
    2. 



    

  • Refresh before expiration
    • 

  • Handle refresh failures gracefully
    • 




Token Lifecycle



    

  • Access Token: Valid for 1 hour
    • 

  • Refresh Token: Valid for 30 days
    • 

  • Refresh before expiration to maintain session
    • 




Troubleshooting



"invalid_client" error

Cause: Incorrect client ID or secret
Solution: Verify credentials in app settings


"redirect_uri_mismatch" error

Cause: Redirect URI doesn't match registered URI
Solution: Must match exactly (including protocol, domain, path)


"invalid_grant" error

Cause: Authorization code expired or already used
Solution: Request new authorization code (codes expire in 10 minutes)


Token expired

Cause: Access token lifetime exceeded
Solution: Use refresh token to get new access token:
bash curl -X POST https://api.example.com/oauth/token \ -d "grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=CLIENT_ID&client_secret=CLIENT_SECRET" 


Still not working?


    

  • Check network connectivity
    • 

  • Verify API status page
    • 

  • Review request/response in browser developer tools
    • 

  • Contact support with request ID
    • 




Quality Standards


    

  • [x] All code examples tested and working
    • 

  • [x] Security review completed
    • 

  • [x] Examples in 3+ languages
    • 

  • [x] Common errors documented
    • 

  • [x] Troubleshooting section complete
    • 

  • [x] Ready for production

Step 10: Self-Review

Check your content against quality standards:

  • [ ] All sections from template completed
  • [ ] Code examples tested and working
  • [ ] No placeholder text remains
  • [ ] Spelling and grammar checked
  • [ ] Technical accuracy verified
  • [ ] Links working (if any)

Phase 4: Mark Progress (2 minutes)

Step 11: Update Batch INDEX

Edit batch-002/INDEX.md:

## Content Items


    

  • [x] OAuth 2.0 Authentication Guide  # Changed [ ] to [x]
    • 

  • [ ] API Key Authentication Guide
    • 

  • [ ] JWT Token Authentication Guide
    • 

  • [ ] Authentication Best Practices
    • 

  • [ ] Common Authentication Errors

Step 12: Commit Your Work

# Stage changes
git add batch-002/


Commit with descriptive message

git commit -m "Complete OAuth 2.0 authentication guide in batch-002"


Push to remote

git push origin main

Verification Checklist

Confirm your batch is properly set up:

# Check batch structure
ls batch-002/

Should show:


INDEX.md


auth-guide-template.md (if created)


oauth-authentication-guide.md



Verify batch INDEX

cat batch-002/INDEX.md | grep Status

Should show: ## Status: In Progress



Check item completion

cat batch-002/INDEX.md | grep "\[x\]"

Should show at least one completed item



Verify main INDEX

grep "batch-002" INDEX.md

Should show: - [ ] batch-002 — In Progress (1/5 titles)



Confirm Git tracking

git status

Should show: nothing to commit (if you committed)

Best Practices

Do's ✓

  1. Plan before creating
  • Know what you're documenting
  • Understand your audience
  • Set clear success criteria
  1. Start small
  • 5-10 items per batch is ideal
  • Can always split into multiple batches
  • Easier to complete and track
  1. Use descriptive names
  • Batch: "User Authentication" not "Batch 2"
  • Items: "OAuth 2.0 Guide" not "Guide 1"
  1. Track dependencies
  • Note in batch INDEX if items depend on each other
  • Complete in logical order
  1. Commit frequently
  • After each completed item
  • Clear commit messages
  • Push to remote regularly

Don'ts ✗

  1. Don't create batches that are too large
  • >15 items becomes unwieldy
  • Split into multiple batches instead
  1. Don't mix unrelated content
  • Keep batches focused on one topic/theme
  • Easier to review and complete
  1. Don't skip the planning phase
  • Saves time in the long run
  • Prevents scope creep
  • Ensures completeness
  1. Don't leave batches incomplete
  • Better to have smaller, complete batches
  • Incomplete batches create technical debt
  1. Don't forget to update tracking
  • Mark items complete as you finish
  • Update counts in main INDEX
  • Keeps stakeholders informed

Common Patterns

Research-Heavy Batch

# Batch 003 — Competitive Analysis


Content Items


    

  • [ ] Competitor A analysis
    • 

  • [ ] Competitor B analysis
    • 

  • [ ] Feature comparison matrix
    • 

  • [ ] Market positioning doc
    • 




Notes

Research phase: Nov 1-15
Writing phase: Nov 16-30
Requires interviews with sales team

Quick-Win Batch

# Batch 004 — Quick Fixes


Content Items


    

  • [ ] Fix typo in installation guide
    • 

  • [ ] Update outdated screenshot
    • 

  • [ ] Add missing link
    • 

  • [ ] Clarify ambiguous section
    • 




Notes

Small updates batch - target 1 day completion

Collaborative Batch

# Batch 005 — Product Launch Docs


Content Items


    

  • [ ] Overview (Alice)
    • 

  • [ ] Technical specs (Bob)
    • 

  • [ ] User guide (Charlie)
    • 

  • [ ] API docs (Diana)
    • 




Notes

Distributed workload - weekly sync meetings
Target: Complete before launch (Dec 1)

Troubleshooting

Can't decide what to include in batch

Solution: Use the "atomic topic" test:
  • Can you describe the batch in one sentence?
  • Are all items related to that sentence?
  • If no, split into multiple batches

Batch growing too large

Solution: Split mid-batch is okay:
  1. Create batch-002-part-1 and batch-002-part-2
  2. Or create batch-002 and batch-003
  3. Update main INDEX accordingly

Unsure about item granularity

Rule of thumb:
  • Each item = 30 min to 4 hours of work
  • If less: Combine items
  • If more: Split into sub-items

Template doesn't fit content type

Solution: Create custom template:
  1. Copy closest existing template
  2. Modify for your needs
  3. Save in templates/ folder
  4. Document when to use it

Next Steps

Now that your first batch is set up:

  1. Complete remaining items
  • Work through unchecked items
  • Follow same process
  • Mark complete as you go
  1. Review and finalize
  • Peer review if working with team
  • Check all quality standards
  • Verify all links work
  1. Mark batch complete
  • When all items checked
  • Update batch status to "Complete"
  • Update main INDEX count
  1. Start next batch
  • Apply lessons learned
  • Refine your process
  • Build momentum

Related Guides

  • How to Set Up X402 in 5 Minutes
  • How to Write Quality Documentation
  • X402 Best Practices
  • X402 Templates Guide

Quality Standards

  • [x] Clear step-by-step instructions
  • [x] Real examples provided
  • [x] Best practices included
  • [x] Troubleshooting section complete
  • [x] Verification steps included
  • [x] Ready for production

Start Building with X402

Get our free X402 Implementation Starter Kit with ready-to-use templates, code examples, and best practices.

What is included:

  • Quick-start implementation templates
  • API integration examples
  • Configuration best practices guide

Get the Free Starter Kit