Coinpayportal

curl -s https://coinpayportal.com/skill.md

CoinPayPortal — Payments, Escrow & Wallets

Non-custodial crypto infrastructure for AI agents and humans. Create wallets, send payments, hold funds in escrow, and receive payments across BTC, ETH, SOL, POL, BCH, and USDC — no KYC required.

Base URL: https://coinpayportal.com/api/web-wallet npm: @profullstack/coinpay

SDK Installation

npm install @profullstack/coinpay
# or
pnpm add @profullstack/coinpay

import { CoinPaySDK } from '@profullstack/coinpay';

const sdk = new CoinPaySDK({
  baseUrl: 'https://coinpayportal.com',
  apiKey: 'your-api-key' // for merchant API
});

// Create a payment
const payment = await sdk.createPayment({
  cryptocurrency: 'ETH',
  amount_usd: 100,
  metadata: { orderId: '123' }
});

The SDK provides typed interfaces for the merchant payment API. For the web-wallet API (non-custodial), use the REST endpoints below.

Quick Start

1. Create a Wallet

curl -X POST https://coinpayportal.com/api/web-wallet/create \
  -H "Content-Type: application/json" \
  -d '{
    "public_key_secp256k1": "<your-compressed-secp256k1-pubkey-hex>",
    "public_key_ed25519": "<your-ed25519-pubkey-base58>",
    "initial_addresses": [
      { "chain": "ETH", "address": "0x...", "derivation_path": "m/44''''/60''''/0''''/0/0" },
      { "chain": "SOL", "address": "...", "derivation_path": "m/44''''/501''''/0''''/0''''" }
    ]
  }'

Response:

{
  "success": true,
  "data": {
    "wallet_id": "uuid-here",
    "created_at": "2024-01-01T00:00:00Z",
    "addresses": [{ "chain": "ETH", "address": "0x...", "derivation_index": 0 }]
  }
}

Save your wallet_id — you need it for all authenticated requests.

2. Authenticate Requests

Sign each request with your secp256k1 private key:

Authorization: Wallet <wallet_id>:<signature>:<timestamp>:<nonce>

Message to sign: {METHOD}:{PATH}:{UNIX_TIMESTAMP}:{BODY}

Example: GET:/api/web-wallet/abc123/balances:1706432100:

Sign the message bytes with secp256k1, hex-encode the 64-byte compact signature.

Nonce (recommended): Append a random string (e.g. 8 chars from crypto.randomUUID()) as the 4th field. This prevents replay errors when firing concurrent requests in the same second. The nonce is optional for backwards compatibility.

3. Check Balances

curl https://coinpayportal.com/api/web-wallet/<wallet_id>/balances \
  -H "Authorization: Wallet <wallet_id>:<signature>:<timestamp>:<nonce>"

Response:

{
  "success": true,
  "data": {
    "balances": [
      { "chain": "BTC", "address": "1...", "balance": "0.01", "updatedAt": "..." },
      { "chain": "ETH", "address": "0x...", "balance": "1.5", "updatedAt": "..." }
    ]
  }
}

4. Send a Transaction

Three-step flow: prepare (server) → sign (local) → broadcast (server).

Step 1 — Prepare:

curl -X POST https://coinpayportal.com/api/web-wallet/<wallet_id>/prepare-tx \
  -H "Authorization: Wallet <wallet_id>:<sig>:<ts>:<nonce>" \
  -H "Content-Type: application/json" \
  -d '{
    "from_address": "0xYourAddress",
    "to_address": "0xRecipient",
    "chain": "ETH",
    "amount": "1000000000000000000",
    "priority": "medium"
  }'

Returns tx_id and unsigned_tx data.

Step 2 — Sign locally using your private key. Never send your private key to the server.

Step 3 — Broadcast:

curl -X POST https://coinpayportal.com/api/web-wallet/<wallet_id>/broadcast \
  -H "Authorization: Wallet <wallet_id>:<sig>:<ts>:<nonce>" \
  -H "Content-Type: application/json" \
  -d '{
    "tx_id": "<from-prepare>",
    "signed_tx": "0x<signed-hex>",
    "chain": "ETH"
  }'

Returns tx_hash, explorer_url, and initial status ("confirming").

5. Sync On-Chain History

Pull external deposits and update transaction confirmations from the blockchain:

curl -X POST https://coinpayportal.com/api/web-wallet/<wallet_id>/sync-history \
  -H "Authorization: Wallet <wallet_id>:<sig>:<ts>:<nonce>" \
  -H "Content-Type: application/json" \
  -d '{ "chain": "BTC" }'

Omit chain to sync all chains. Indexed transactions are marked with metadata.source: "indexer".

A background daemon also runs server-side, automatically finalizing pending/confirming transactions every 15 seconds — so transactions will update even if the client disconnects.

6. Webhooks

Register a webhook URL to get notified of transaction status changes:

curl -X PATCH https://coinpayportal.com/api/web-wallet/<wallet_id>/settings \
  -H "Authorization: Wallet <wallet_id>:<sig>:<ts>:<nonce>" \
  -H "Content-Type: application/json" \
  -d '{ "webhook_url": "https://your-server.com/webhook" }'

Supported Chains

All Endpoints

Transaction Lifecycle

1. Prepare → creates a pending record with unsigned_tx
2. Sign → done client-side with your private key
3. Broadcast → sends to blockchain, status becomes confirming
4. Finalization → background daemon checks on-chain confirmations every 15s, updates to confirmed or failed

Transactions are also synced from the blockchain via the indexer — external deposits you receive will appear in your history automatically.

Transaction Statuses

Required Confirmations

CLI

The wallet CLI provides command-line access to all wallet operations:

# Install / setup
cd coinpayportal
echo '{ "apiUrl": "https://coinpayportal.com" }' > ~/.coinpayrc.json

# Create a new wallet (outputs wallet_id + mnemonic)
pnpm coinpay-wallet create --words 12 --chains BTC,ETH,SOL

# Import from mnemonic
pnpm coinpay-wallet import "word1 word2 ... word12" --chains BTC,ETH,SOL,POL,BCH

# Check balances
pnpm coinpay-wallet balance <wallet-id>

# List addresses
pnpm coinpay-wallet address <wallet-id> --chain ETH

# Send transaction
pnpm coinpay-wallet send <wallet-id> \
  --from 0xYourAddr --to 0xRecipient --chain ETH --amount 0.1 --priority medium

# Transaction history
pnpm coinpay-wallet history <wallet-id> --chain BTC --limit 10

# Sync on-chain deposits
pnpm coinpay-wallet sync <wallet-id> --chain SOL

Environment variables:

• COINPAY_API_URL — API base URL (default: http://localhost:8080)
• COINPAY_AUTH_TOKEN — JWT token for read-only operations
• COINPAY_MNEMONIC — Mnemonic phrase (required for send)

Escrow Service

Create trustless escrows to hold funds until both parties are satisfied. No accounts required — authentication uses unique tokens.

Create Escrow

curl -X POST https://coinpayportal.com/api/escrow \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "ETH",
    "amount": 0.5,
    "depositor_address": "0xAlice...",
    "beneficiary_address": "0xBob...",
    "expires_in_hours": 48
  }'

Response:

{
  "id": "uuid",
  "escrow_address": "0xDeposit...",
  "status": "created",
  "release_token": "esc_abc123...",
  "beneficiary_token": "esc_def456...",
  "amount": 0.5,
  "fee_amount": 0.005,
  "expires_at": "2024-01-03T12:00:00Z"
}

Save both tokens — they are only returned once. Depositor gets release_token, beneficiary gets beneficiary_token.

Escrow Flow

1. Create → get deposit address + tokens
2. Fund → depositor sends crypto to escrow_address (auto-detected)
3. Release → depositor calls release, funds forwarded to beneficiary minus fee
4. OR Refund → depositor calls refund, full amount returned (no fee)
5. OR Dispute → either party opens dispute

Escrow Endpoints

Release Funds

curl -X POST https://coinpayportal.com/api/escrow/<id>/release \
  -H "Content-Type: application/json" \
  -d '{ "release_token": "esc_abc123..." }'

Refund

curl -X POST https://coinpayportal.com/api/escrow/<id>/refund \
  -H "Content-Type: application/json" \
  -d '{ "release_token": "esc_abc123..." }'

Dispute

curl -X POST https://coinpayportal.com/api/escrow/<id>/dispute \
  -H "Content-Type: application/json" \
  -d '{
    "token": "esc_def456...",
    "reason": "Work not delivered as agreed"
  }'

Escrow Statuses

Escrow SDK

const escrow = await client.createEscrow({
  chain: 'SOL', amount: 10,
  depositor_address: 'Alice...',
  beneficiary_address: 'Bob...',
});

// Release
await client.releaseEscrow(escrow.id, escrow.release_token);

// Refund
await client.refundEscrow(escrow.id, escrow.release_token);

// Wait for settlement
const settled = await client.waitForEscrow(escrow.id, 'settled');

Escrow CLI

coinpay escrow create --chain SOL --amount 10 \
  --depositor Alice... --beneficiary Bob...
coinpay escrow get <id>
coinpay escrow list --status funded
coinpay escrow release <id> --token esc_abc...
coinpay escrow refund <id> --token esc_abc...
coinpay escrow dispute <id> --token esc_def... --reason "..."
coinpay escrow events <id>

Fees

• Free tier: 1% on release
• Professional: 0.5% on release
• Refunds: No fee

Business Accounts (for AI Agents)

AI agents can create business accounts to get reduced escrow fees (0.5% vs 1%) and track payments/escrows in one place.

Create Business

curl -X POST https://coinpayportal.com/api/businesses \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "RiotCoder Services",
    "description": "AI coding agent — code review and bug fixes",
    "webhook_url": "https://your-server.com/webhook"
  }'

Returns business id and api_key. Use the business_id when creating escrows for the reduced fee rate.

List Businesses

curl https://coinpayportal.com/api/businesses \
  -H "x-api-key: <your-api-key>"

Create Escrow with Business

curl -X POST https://coinpayportal.com/api/escrow \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "SOL",
    "amount": 10,
    "depositor_address": "Alice...",
    "beneficiary_address": "Bob...",
    "business_id": "<your-business-id>"
  }'

Rate Limits

Key Principles

• Non-custodial: Your private keys never touch our servers
• Anonymous: No email, no KYC — your seed phrase is your identity
• Multi-chain: 8 assets across 5 blockchains
• Signature auth: Every request is signed with your key (nonce prevents replay)
• API-first: Built for programmatic access by AI agents
• Background finalization: Daemon confirms transactions even if the client disconnects
• On-chain indexing: External deposits are automatically detected and indexed

Converted and distributed by TomeVault — claim your Tome and manage your conversions.